Welcome to Jun Ma’s documentation!

Heading to Sphinx and Read the Docs

Note

This page is only used to document the information I gathered and the process I went through when I did pratices on Git, ReadtheDocs, and Sphinx.

Background

Treating documentation as code is becoming a major theme in the software industry.

The following advanced tools and platforms are widely used by both developers and technical writers.

• Sphinx provides a documentation generator that is best-in-class for software docs. Sphinx documents are written in the reStructuredText markup language. reStructuredText is a powerful language primarily because the syntax can be extended.
• Read the Docs is a hosting platform for Sphinx-generated documentation. It takes the power of Sphinx and adds version control, full-text search, and other useful features. It pulls down code and doc files from Git, Mercurial, or Subversion, then builds and hosts your documentation.
• GitHub is a code hosting platform for version control and collaboration.

Preparations

• Run python-3.7.5-amd64.exe to install Python 3.7.5
• Run pip install -U Sphinx in the command prompt to install Sphinx
• Run Sublime Text Build 3211 x64 Setup.exe to install Sublime
• Run Git-2.25.0-64-bit.exe to install Git
• Create an account in Read the Docs and Github

Steps

1. Run $ sphinx-quickstart in the command prompt to build a directory for Sphinx output.

2. Enrich the master file index.rst and other source files by using Sublime.

   Tip

   To learn more Sphinx syntax, refer to https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html.

3. Create an open-source repo in Github.

4. Commit the local directory and files to your Github Repo by running the following commands in Git Bash.

   • Verify Identity: $ git config --global user.email "registered email address"
   • Verify Identity: $ git config --global user.name "registered user ID"
   • Connect to Github Repo: $ git remote add origin https://github.com/"UserID"/"RepoID".git
   • Create a Pull Request and Merge: $ git pull origin master --allow-unrelated-histories
   • Add all files: $ git add *
   • Commit all files you added: $ git commit -m "description"
   • Push and merge updates: $ git push -u origin master

5. Link your GitHub repo to your Read the Docs account.

6. Build and View in Read the Docs.

Working with Sphinx

Change a Theme

1. Run pip install sphinx_rtd_theme to install the Read The Docs theme.
2. In the conf.py file, add html_theme = 'sphinx_rtd_theme'.

Add a Logo Image

1. Place the logo.png file to the source/_static folder.
2. In the conf.py file:

• Add html_logo = './_static/logo.png'.
• Add the following argument:

html_theme_options = {

'canonical_url': '',
'analytics_id': 'UA-XXXXXXX-1', #  Provided by Google in your dashboard
'logo_only': True,                              #  Set as "True" to display logo only
'display_version': True,
'prev_next_buttons_location': 'bottom',
'style_external_links': False,
'vcs_pageview_mode': 'raw',
'style_nav_header_background': '#2980B9',
'collapse_navigation': True,
'sticky_navigation': False,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False

}

Insert a Table

Input

Result

Header A	Header B	Header C
A1	B1	C1
A2	B2	C2

Insert an Image

1. Place the picture.jpg file to the source/_static folder.
2. Add .. image:: /_static/picture.jpg in the rst file.

Working with Read the Docs

Multi-version

1. Create a new branch for your project on Github.
2. On the Versions tab of RTD, activate the new version (synced from Github).
3. Build the new version.

Multi-language for Localization

Step 1 Create Translatable Files

Run $ sphinx-build -b gettext . _build/gettext in the source/ directory to create pot files.

Step 2 Translate Text from Source Language

1. Run $ pip install-intl to install the sphinx-intl tool.
2. Run $ sphinx-intl update -p _build/gettext -l ja_JP to generate a directory structure like below:

locale
├── ja_JP
│   └── LC_MESSAGES
│       └── index.po

Then open those .po files with a text editor and translate the content in the msgstr argument.

Step 3 Build the Documentation in Target Language

#. Run $ sphinx-build -b html -D language=ja_JP . _build/html/ja_JP to build the documentation in Japanese. #.

Reference:

• https://docs.readthedocs.io/en/stable/guides/manage-translations.html
• https://docs.readthedocs.io/en/stable/localization.html
• https://www.icanlocalize.com/site/tutorials/how-to-translate-with-gettext-po-and-pot-files/
• https://www.drupal.org/node/1814954

Working with Git

Commit Changes to A New Branch

For example, the current branch I’m working on is named master, and the other branch is named stable.

1. Run $ git checkout -b stable to switch to the new branch.
2. Edit files and save.
3. Run $ git commit <file> -m "sync with master" to commit a single change to your local repo.
4. Run $ git push origin stable to push the change to the new branch on the Github.

Merge Changes into the Master Branch

The current branch I’m working on is named stable.

1. Run $ git checkout master to switch to the master branch.
2. Run $ git merge stable.

Cooking

Breakfast

Day 1

• Fried Egg
• Fried Dumpling
• Coffee

Day 2

• Hand-grasping Cake + Pork Luncheon Meat + Scrambled Egg
• Coffee

Day 3

• Sumai
• Steamed Bun
• Coffee

Lunch/Dinner

Meal 1

• Rice
• Cucumber + Shrimp
• Green Pepper + Egg

Meal 2

• Rice
• Fish Fillet
• Spinach Soup

Meal 3

Meal 4

• Rice
• Sausage + Dried Tofu
• Mushroom + Shrimp
• Soup

Meal 5

• Rice
• Tomato + Eggs
• Cabbage + Sausage
• Mushroom Soup

Meal 6

• Noodles
• Green Vegetables
• Pork Luncheon Meat
• Egg

Meal 7

• Noodles
• Tomato + Cabbage
• Pork Luncheon Meat
• Egg