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
Content
- What is ReadtheDocs
- Build Environment
- Write your 1st Documentation
- Host on GitHub
- Display in ReadtheDoc
- Multiple Language Support
0. What is ReadtheDocs
ReadtheDocs
ReadtheDocs simplifies software documentation by automating
building, versioning, and hosting of your docs for you；
Link: Read the Docs Homepage
0. What is ReadtheDocs
Sphinx
Link: Sphinx Python Documenation Generator
reStructuredText
- plaintext
- markup language
Link: reStructuredText
1. Build Environment (2)
Upon install Python3, type the comments below in your comment prompt to check whether Python and Pip has been installed correctly:
python --version
pip --version
install Sphinx using pip tool using the code:
pip install sphinx
1. Build Environment (3)
Executes the comment below in a sepecific folder to further create a sphinx docs project:
sphinx-quickstart
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)
- Python 3.x
- Homebrew
- Terminal
- Xcode with Command Line Tool
1. Build Environment for MacOS (2)
Upon installed python3, type the following command in Terminal to check if it is installed correctly:
python3 --version
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
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
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:
xcode-select --install
1. Build Environment for MacOS (5)
After the installation of all required softwares, install Sphinx using brew tool using the command:
brew install sphinx-doc
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 to PATH:
brew link sphinx-doc --force
Use below command to check if you have successfully installed sphinx:
sphinx-build --version
1. Build Environment for MacOS (6)
Execute the following command in a specific folder to create a sphinx docs project:
sphinx-quickstart
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.html
2. Write your 1st Documentation
Please edit in index.rst and make html
You will find the expected html view in the build folder, and under the html folder, you can see there is a file name called index.html.
3&4. Host on GitHub & Display in ReadtheDocs
- Host your locally created sphinx files into a specific GitHub repository
- Create an account in ReadtheDocs and linked it with your GitHub account
- Create new project in ReadtheDocs by importing from your GitHub repository
3&4. Host on GitHub & Display in ReadtheDocs
- At the homepage, click your profile that is located at the top right.
3&4. Host on GitHub & Display in ReadtheDocs
- Press Import a project
3&4. Host on GitHub & Display in ReadtheDocs
- U will see the whole list of project that are in your Github. Click the + beside the repository that you want to import to ReadtheDocs.
3&4. Host on GitHub & Display in ReadtheDocs
- Fill in all the required details of your projects and click Next.
3&4. Host on GitHub & Display in ReadtheDocs
- Wait until the build process is done. A
Passsingmeans the process is successful while aFailingmeans that something have gone wrong or any setup is wrong during the process.
3&4. Host on GitHub & Display in ReadtheDocs
- In the event when the build process fails. You can analyze the errors that have caused the process to fail. By going into the project and then go into Builds where you can see the details of all the passed or failed processes for the particular project.
3&4. Host on GitHub & Display in ReadtheDocs
- This is an example of how the error message looks.
3&4. Host on GitHub & Display in ReadtheDocs
- To take a look at the ReadtheDocs, press
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
- Create another sphinx folder locally with language setting changed to another language.
- Manually import the newly created folder into the same GitHub repository
- In ReadtheDocs, modify path to
conf.pytab, language settings and translation bar- First go to the
Admintab. Then under theAdmintab tab change the language to the language that you want to change to.
- First go to the
- Next go to the Advanced Settings tab and under the Default Setting, and Python Configuration File enter the path of the correct path to conf.py and save.
-
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