Sphinx Note¶
Installing Sphinx¶
Installation from PyPI¶
pip install -U sphinx
Windows¶
- Download Python 3.7.x
pip install -U sphinx
Markdown¶
Configuration¶
pip install --upgrade recommonmark
extensions = ['recommonmark']
source_suffix
source_suffix = { '.rst': 'restructuredtext', '.txt': 'markdown', '.md': 'markdown', }
sphinx-markdown-tables¶
pip install sphinx-markdown-tables
conf.py
extensions = [ 'sphinx_markdown_tables', ]
Sphinx Comments¶
pip install sphinx-comments
conf.py
extensions = [ 'sphinx_comments', ] comments_config = { "utterances": { "repo": "github-org/github-repo", "optional": "config", } }
Read the Docs¶
pip install sphinx_rtd_theme
sphinx-quickstart
- Separate source and build directories (y/n) [n]:
y
- Project language [en]:
zh_CN
- Separate source and build directories (y/n) [n]:
make html
Windows¶
make.bat html
Build¶
- https://readthedocs.org/
- Sign in with GitHub
- 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
Upgrade pip¶
python -m pip install --upgrade pip
pip -V