Dakamaster's homepage

Bookmark this to keep an eye on my project updates!

Project maintained by S10143806H Hosted on GitHub Pages — Theme by mattgraham

Build Documentation with Sphinx + ReadtheDoc

:information_source: Click HERE to open Presenter View

Content

  1. What is ReadtheDocs
  2. Build Environment
  3. Write your 1st Documentation
  4. Host on GitHub
  5. Display in ReadtheDoc
  6. 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

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` 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 specific 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)

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

  1. Host your locally created sphinx files into a specific GitHub repository
  2. Create an account in ReadtheDocs and linked it with your GitHub account
  3. Create new project in ReadtheDocs by importing from your GitHub repository

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

  1. Wait until the build process is done. A Passsing means the process is successful while a Failing 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

  1. To take a look at the ReadtheDocs, press View Docs

3&4. Host on GitHub & Display in ReadtheDocs

Now your file is fully uploaded into ReadtheDocs server and can be viewed by everyone that knows your hyperlink.

5. Multiple Language Supporting

Method 1: Dual Language Supporting

  1. Create another sphinx folder locally with language setting changed to another language.
  1. Manually import the newly created folder into the same GitHub repository
  1. In ReadtheDocs, modify path to `conf.py` tab, language settings and translation bar
    • First go to the `Admin` tab. Then under the `Admin` tab tab change the language to the language that you want to change to. Imgur
  1. After that, go to translations and press Add
  1. Wait until the build process is finished, then you are able to view the dual language files online

Method 2: Dual Language Supporting

.pot portable object template .po portable object files (for translator) .mo machine object files

Step 1.

pip install sphinx-intl

Step 2. Add configuration to conf.py

locale_dirs = ['locale/'] #path is example but not recommended.
gettext_compact = False   #optional

Step 3. Extract translatable messages into pot files.

$ make gettext

Step 4. Generate .po files We will use the pot files generated in the above step.

$ sphinx-intl update -p build/gettext -l zh_CN -l zh_TW

Once completed, the generated .po files will be placed in the below directories:

Step 5. Translate .po files

Step 6 Build translated document

make -e SPHINXOPTS-" -D language='zh_TW'html

Live Streaming Records

References