sphinx使用探索

环境搭建

安装依赖包

mkvirtualenv
pip install Sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx_markdown_tables

配置文件

操作命令

生成项目目录

sphinx-quickstart

执行后生成的目录结构
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates

• Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
• build：生成的文件的输出目录。
• make.bat：Windows 用命令行。
• _static：静态文件目录，比如图片等。
• _templates：模板目录。
• conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 时选中的那些值，可以自行定义其他的值。
• index.rst：文档项目起始文件。

生成html

make html

生成latex

make latex

启动web服务查看

sphinx-autobuild source build/html --port 8009 --host 172.18.18.204

配置

支持Markdown

在conf.py中修改以下内容

extensions = [
    'recommonmark',
    'sphinx_markdown_tables'
]

修改主题

在conf.py中添加以下内容

html_theme = 'sphinx_rtd_theme'

支持的主体有：alabaster、classic、sphinx_rtd_theme、furo
注意需要先安装对应的主体，如press，furo等

pip install sphinx-press-theme
pip install furo
pip install sphinx-documatt-theme
pip install sphinx-book-theme

定制页脚

添加layout.html到_templates目录下

{% extends '!layout.html' %}

{% block footer %}
<!-your footer content->
{% endblock %}

例如：

{% extends '!layout.html' %}

{% block footer %}
<div class="footer">
南京跑码地计算技术有限公司©2020-2022 CooVally&nbsp;|&nbsp;<a href="https://beian.miit.gov.cn/">苏ICP备2022012159号-1</a>
</div>
{% endblock %}

支持中文搜索[新版本默认已支持中文]

安装jieba分词

pip install jieba

• 安装sphinx.search.zh_CN 插件，从github下载zh_CN.py。

• 将zh_CN.py复制到sphinx的search目录下，如：/opt/virtualenvs/doc/lib/python3.8/site-packages/sphinx/search。

• 打开 search 目录下的 init.py 找到：

• from sphinx.search import en, ja
  languages = {
      'en': en.SearchEnglish,
      'ja': ja.SearchJapanese,
  }
  

  修改为

  from sphinx.search import en, ja, zh_CN
  languages = {
      'en': en.SearchEnglish,
      'ja': ja.SearchJapanese,
      'zh_CN': zh_CN.SearchChinese
  }
  

参考

• 定制页脚：https://www.sphinx-doc.org/en/master/templating.html
• sphinx支持的主题：https://sphinx-themes.org/
• sphinx支持中文搜索：https://www.jianshu.com/p/d99f1b399ddc， https://github.com/bosbyj/sphinx.search.zh_CN