Skip to content

Build Your First ReadtheDocs

Jump to bottom
ambiot edited this page Feb 8, 2022 · 1 revision

How to create AmebaIoT Documentation with Sphinx + ReadtheDoc

ℹ️ Click HERE to open Presenter View

0. What is ReadtheDocs

ReadtheDocs

ReadtheDocs simplifies software documentation by automating building, versioning, and hosting of your docs for you；

Sphinx

reStructuredText

1. Build Environment

Setup on Windows

Required Softwares (for Windows)

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

Executes the comment below in a specific folder to further create a sphinx docs project:

sphinx-quickstart

Opens Cygwin and install make & chere packages accordingly. Runs make html in the same file path, then you will find your first readthedoc documentation.

Setup on MacOS

Required Softwares (for MacOS)

Upon installing 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.

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)"

You can download Xcode from the 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

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

Execute the following command in a specific folder to create a sphinx docs project:

sphinx-quickstart

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. Create 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 a new project in ReadtheDocs by importing it from your GitHub repository

    • At the homepage, click your profile that is located at the top right.

    • Press Import a project

    • You will see the whole list of projects that are in your Github. Click the + beside the repository that you want to import to ReadtheDocs.

    • Fill in all the required details of your projects and click Next.

  4. Wait until the build process is done. A Passing means the process is successful while a Failing means that something has gone wrong or any setup is wrong during the process.

    • 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.
    • This is an example of how the error message looks.

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

Now your file is fully uploaded into the 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 the language setting changed to another language.

  2. Manually import the newly created folder into the same GitHub repository

  3. In ReadtheDocs, modify path to conf.py tab, language settings and translation bar

    • First go to the Admin tab. Then under the Admin 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.

  4. After that, go to translations and press Add

  5. Wait until the build process is finished, then you are able to view the dual-language files online

Method 2: Multiple Language Supporting

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

  1. pip install sphinx-intl

  2. Add configuration to conf.py

locale_dirs = ['locale/'] #path is example but not recommended.
gettext_compact = False   #optional
  1. Extract translatable messages into pot files.

$ make gettext

  • The generated .pot files will be placed in the build/gettext directory.
  1. 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/

  1. Translate .po files

  2. Build translated document make -e SPHINXOPTS-" -D language='zh_TW'html

Live Streaming Records (CN)

Clone this wiki locally