or
or
By clicking below, you agree to our terms of service.
New to HackMD? Sign up
Syntax | Example | Reference | |
---|---|---|---|
# Header | Header | 基本排版 | |
- Unordered List |
|
||
1. Ordered List |
|
||
- [ ] Todo List |
|
||
> Blockquote | Blockquote |
||
**Bold font** | Bold font | ||
*Italics font* | Italics font | ||
~~Strikethrough~~ | |||
19^th^ | 19th | ||
H~2~O | H2O | ||
++Inserted text++ | Inserted text | ||
==Marked text== | Marked text | ||
[link text](https:// "title") | Link | ||
 | Image | ||
`Code` | Code |
在筆記中貼入程式碼 | |
```javascript var i = 0; ``` |
|
||
:smile: | ![]() |
Emoji list | |
{%youtube youtube_id %} | Externals | ||
$L^aT_eX$ | LaTeX | ||
:::info This is a alert area. ::: |
This is a alert area. |
On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?
Please give us some advice and help us improve HackMD.
Do you want to remove this version name and description?
Syncing
xxxxxxxxxx
20210902 Accomdey: Build Documentation with Sphinx + ReadtheDoc
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →Content
0. What is ReadtheDocs
ReadtheDocs
Link: Read the Docs Homepage
0. What is ReadtheDocs
Sphinx
Link: Sphinx Python Documenation Generator
reStructuredText
Link: reStructuredText
1. Build Environment (1)
Required Softwares (for Windows)
1. Build Environment (2)
Upon install Python3, type the comments below in your comment prompt to check whether
Python
andPip
has been installed correctly:install
Sphinx
usingpip
tool using the code:1. Build Environment (3)
Executes the comment below in a sepecific folder to further create a sphinx docs project:
1. Build Environment (4)
Opens Cygwin and install
make
&chere
packages accordingly.Runs
make html
in the same file path, then you will find your first readthedoc documentation.1. Build Environment for MacOS (1)
Required Softwares (for MacOS)
1. Build Environment for MacOS (2)
Upon installed python3, type the following command in Terminal to check if it is installed correctly:
If it is correctly installed, you will be able to see the version number of your python3.
1. Build Environment for MacOS (3)
To install Homebrew to MacOS, type the following command in your Terminal
1. Build Environment for MacOS (4)
You can download Xcode from Apple store. If Command Line Tools is not installed together with your Xcode, you can use the following command to install Command Line Tools:
1. Build Environment for MacOS (5)
After the installation of all required softwares, install
Sphinx
usingbrew
tool using the command:At the end of the installation, you may see a warning that shows sphinx is "keg-only" and is not by default put in your
PATH
, use the follwoing command to link it toPATH
:Use below command to check if you have successfully installed
sphinx
:1. Build Environment for MacOS (6)
Execute the following command in a specific folder to create a sphinx docs project:
1. Build Environment for MacOS (7)
Open Terminal in the same folder that contains makefile, and execute the command

make html
, now you will find your first ReadtheDocs documentation in /build/html/index.html2. Write your 1st Documentation
Please edit in
index.rst
andmake html
You will find the expected html view in the
build
folder, and under thehtml
folder, you can see there is a file name calledindex.html
.3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
Passsing
means the process is successful while aFailing
means that something have gone wrong or any setup is wrong during the process.3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
3&4. Host on GitHub & Display in ReadtheDocs
View Docs
3&4. Host on GitHub & Display in ReadtheDocs
Now your file is fully uplaoded into ReadtheDocs server and can be viewed by everyone that knows your hyperlink.
5. Multiple Language Supporting
Method 1: Dual Language Supporting
conf.py
tab, language settings and translation barAdmin
tab. Then under theAdmin
tab tab change the language to the language that you want to change to.After that, go to translations and press Add

Wait until the build process is finished, then you are able to view the dual language files online
Live Streaming Records
References