Sphinx Note๏ƒ

Overview๏ƒ

Sphinx is written in Python and supports Python 3.5+.

Installing Sphinx๏ƒ

Linux๏ƒ

RHEL, CentOS

yum install python-sphinx

Installation from PyPI๏ƒ

pip install -U sphinx

Windows๏ƒ

  1. Download Python 3.7.x

  2. pip install -U sphinx

Markdown๏ƒ

Configuration๏ƒ

  1. pip install --upgrade recommonmark

  2. extensions = ['recommonmark']

  3. source_suffix

    source_suffix = {
	'.rst': 'restructuredtext',
	'.txt': 'markdown',
	'.md': 'markdown',
}

sphinx-markdown-tables๏ƒ

  1. pip install sphinx-markdown-tables

  2. conf.py

    extensions = [
	'sphinx_markdown_tables',
]

Sphinx Comments๏ƒ

  1. pip install sphinx-comments

  2. conf.py

    extensions = [
	'sphinx_comments',
]
comments_config = {
   "utterances": {
      "repo": "github-org/github-repo",
      "optional": "config",
   }
}

Read the Docs๏ƒ

  1. pip install sphinx_rtd_theme

  2. sphinx-quickstart

    • Separate source and build directories (y/n) [n]: y

    • Project language [en]: zh_CN

  3. make html

Windows๏ƒ

make.bat html

Build๏ƒ

  1. https://readthedocs.org/

  2. Sign in with GitHub

  3. Import a Project

Tips๏ƒ

Read the Docs๏ƒ

  • requirements.txt

  • Fix latexmk -r latexmkrc -pdf: *.gif

  • https://readthedocs.org/ -> ้กน็›ฎ -> ็ฎก็† -> ่ฎพ็ฝฎ -> ๅ็งฐ: frameworks

  • Fix ImportError: cannot import name 'PackageFinder' from 'pip._internal.index':

    • Go to Versions

    • Click on the Edit button of the version you want to wipe on the right side of the page

    • Go to the bottom of the page and click the wipe link, next to the โ€œSaveโ€ button

  • Fix Could not import extension sphinx.builders.linkcheck: use a config file (https://docs.readthedocs.io/en/stable/config-file/v2.html)

References๏ƒ