Skip to content

Latest commit

 

History

History
326 lines (212 loc) · 9.78 KB

new-post.md

File metadata and controls

326 lines (212 loc) · 9.78 KB
Raw

Build Documentation with Sphinx + ReadtheDoc

ℹ️ 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

  • plaintext
  • markup language

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

  • 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

  • You 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

  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

  • 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

  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
  • 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.
  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

  • The generated .pot files will be placed in the build/gettext directory.

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:

  • ../locale/zh_CN/LC_MESSAGES/
  • ../locale/zh_TW/LC_MESSAGES/

Step 5. Translate .po files

Step 6 Build translated document

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

Live Streaming Records

References