Sphinx Note

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

Sphinx Book Theme#

  1. pip install sphinx-book-theme

  2. conf.py

    html_theme = "sphinx_book_theme"
html_theme_options = {
    "path_to_docs": "doc/source",
    "repository_url": "https://github.com/T5750/framework-repositories",
    "repository_branch": "master",
    "use_source_button": True,
    "use_edit_page_button": True,
    "use_issues_button": True,
}

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#

Contents