sphix是一个文档生成工具
本文介绍一些基础技能，如果想深入学习，可以查看官方文档
Sphinx官方文档
1.安装虚拟环境
# ubuntu
# 使用 venv 创建 .venv虚拟环境
python3 -m venv .venv# 激活虚拟环境
source .venv/bin/activate# windows
# 创建虚拟环境
python -m venv .venv# 激活虚拟环境
.venv\Scripts\activate.bat2.安装sphinx
(.venv) $ pip install -U sphinx
3.创建文档项目
(.venv) $ sphinx-quickstart docs
具体步骤如下图：
4.项目docs目录结构
docs
├── build
├── make.bat
├── Makefile
└── source├── conf.py├── index.rst├── _static└── _templates
build/
一个空目录（目前），用于保存渲染的文档。make.bat和Makefile
用于简化一些常见 Sphinx 操作的便捷脚本，例如 渲染内容。source/conf.py
一个 Python 脚本，用于保存 Sphinx 项目的配置。它包含 您指定的 Project Name 和 Release 以及 作为一些额外的配置键。sphinx-quickstartsource/index.rst
项目的根文档，用作欢迎页面和 包含“目录树”（或 TOCTREE）的根
5.编译docs项目
假如你当前和docs目录在同一级目录
(.venc) $ sphinx-build -M html docs/source/ docs/build/
编译步骤如下：
编译生成的目录如下：
用浏览器打开index.html如下图：
6.修改index.rst
index.rst是html的首页，它 是用 reStructuredText（一种强大的标记语言）编写的。
修改内容如下:
docs/source/index.rst
Welcome to Lumache's documentation!
===================================**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients. It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API... note::This project is under active development.
重新编译
(.venv) $ cd docs
(.venv) $ make html
build/html/index.html的内容也改变了
7.使用内置扩展
docs/source/conf.py
# 添加sphinx支持的扩展
# 一种是内置扩展如 'sphinx.ext.*' 或者自定义扩展
# 其中一种内置扩展如下
extensions = ['sphinx.ext.duration',
]
(.venv) $ make html
每次编译的时候会有一些测量编译时间的信息生成。
====================== slowest reading durations =======================
0.031 index
build succeeded.The HTML pages are in build\html.
sphinx支持的内置扩展如下:
- sphinx.ext.autodoc – Include documentation from docstrings
- sphinx.ext.autosectionlabel – Allow referencing sections by their title
- sphinx.ext.autosummary – Generate autodoc summaries
- sphinx.ext.coverage – Collect doc coverage stats
- sphinx.ext.doctest – Test snippets in the documentation
- sphinx.ext.duration – Measure durations of Sphinx processing
- sphinx.ext.extlinks – Markup to shorten external links
- sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
- sphinx.ext.graphviz – Add Graphviz graphs
- sphinx.ext.ifconfig – Include content based on configuration
- sphinx.ext.imgconverter – A reference image converter using Imagemagick
- sphinx.ext.inheritance_diagram – Include inheritance diagrams
- sphinx.ext.intersphinx – Link to other projects’ documentation
- sphinx.ext.linkcode – Add external links to source code
- Math support for HTML outputs in Sphinx
- sphinx.ext.napoleon – Support for NumPy and Google style docstrings
- sphinx.ext.todo – Support for todo items
- sphinx.ext.viewcode – Add links to highlighted source code
8.使用第三方HTML主题
修改html主题
docs/source/conf.py
#此处主题可以选择内置主题，或者第三方主题
html_theme = 'furo'
如果选择第三方主题,比如 ‘furo’,需要安装此主题：
(.venv) $ pip install furo
sphinx内置的html主题可以参考如下链接:
内置主题
sphinx第三方主题如下链接:
第三方主题链接
设置好主题后编译
(.venv) $ make html
9.创建多个页面
在docs/source文件夹创建多个页面
比如usage.rst,1.rst,2.rst,3.rst
然后在index.rst文件中添加它们
内容如下:
usage.rst内容
Usage
=====.. _installation:Installation
------------To use Lumache, first install it using pip:.. code-block:: console(.venv) $ pip install lumache
1.rst内容
1.rst
========
2.rst,3.rst同上，只是序号不同
将上面4个.rst文件添加到主页面index.rst
.. toctree::usage123
编译
make html
