0%

Write API with Sphinx+ReadTheDocs

Setting up ๐ŸŒ

  • Install Sphinx:
1
pip install sphinx sphinx-autobuild
  • Create project
1
2
3
mkdir testProject
cd testProject
sphinx-quickstart
  • Project Configuration

Start project configuration after sphinx-quickstart. Generally, only three items need to be entered manually, and the rest can be directly typed Enter.

1
2
3
1. > Project name: sphinxtestProject
2. > Author name(s): Tom
3. > Project version []: 1.0.1
  • View display

After compiling, drag testProject/_build/html/index.html to the browser to view the display.Compile html:

1
make html

Plugin ๐Ÿ’ก

  • Markdown plugin

Support markdown to html, you need to install pip install recommonmark.Then add in conf.py:

1
2
3
4
source_parsers={
'.md': 'recommonmark.parser.CommonMarkParser'
}
source_suffix=['.rst','.md']
  • Markdownโ€™s form plugin

Need to install pip install sphinx-markdown-tables.Then add in conf.py:

1
2
3
extensions = [
'sphinx_markdown_tables',
]

Theme ๐Ÿ‘•

Replace the theme

  • Change to the most common Blue Grey with the left side of the theme
  • Install pip install sphinx_rtd_theme
  • Open conf.py and replace the original html_theme = 'alabaster' with html_theme = 'sphinx_rtd_theme'

Modify the style based on sphinx_rtd_theme
The items that can be modified can be found in Official Document. Add in conf.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// logo image, you need to put the image in the corresponding path
html_logo = './_static/logo.png'

// Note this configuration. Files placed in the '_static' folder will overwrite the corresponding files created by the build, so the style files that need to be modified can be placed in the _static path.
html_static_path = ['_static']

// Do not display the rst source file link in the html page
html_show_sourcelink = False

// The subtitle of the page label
html_title = 'xxx API'

// small icon for web page tags
html_favicon = './_static/favicon.ico'

Modify code block color scheme

  • Color scheme selection
  • Add pygments.css file under _static and copy the css content into it.

Hosting ๐Ÿ“ˆ

  • Login to readthedocs official website
  • import a Project
  • Manual import
  • Fill in git url
  • Administration -> Advanced Settings
    • The sphinx_markdown_tables plugin is used above. Fill in a file name in the โ€œRequire pip request file to build your documentโ€ column, the content of this file is sphinx-markdown-tables==0.0.9
    • Do not enable PDF build
    • Do not enable EPUB build
  • Click to build