00068 Sphinx 杂项-ubuntu
前言
Sphinx 是一个能自动生成文档的工具,主要用于 Python 语言。
官网: https://www.sphinx-doc.org/en/master/ 。
其中下面三个著名工具网站就是应用它来生成文档的。
python: https://docs.python.org/3/ .
NumPy: https://numpy.org/doc/stable/ .
Pytorch: https://pytorch.org/docs/stable/index.html .
操作系统:Ubuntu 20.04.4 LTS
参考文档
学习路线
-
首先学习如何部署到 Read the Docs,可以看 Read the Docs 的官方教程。
-
然后学习一个非常好的学习例子。
-
之后学习 Read the Docs 设计的主题的教程。
-
最后学习 Sphinx官方教程。
插件 - sphinx-autopackagesummary
插件项目地址: https://github.com/rdb/sphinx-autopackagesummary .
该插件弥补了 sphinx 内置的 autosummary 指令不能处理深层嵌套的问题。
再也不用这样生成 API 文档了。
1 | .. autosummary:: |
仅仅这样写就可以了。
1 | .. autopackagesummary:: mypackage |
安装
- 安装 (如果文档部署在 Read the Docs, 记得在
requirements.txt
文件增加该包名):
1 | pip install sphinx-autopackagesummary |
- 在
conf.py
中开启它.
1 | extensions = ['sphinx.ext.autosummary', 'sphinx_autopackagesummary'] |
使用
- 如果您的包有子包,则可以通过自定义
autosummary
模板来递归地使用它。例如,您可以将根包记录如下:
1 | .. autopackagesummary:: mypackage |
- 创建一个模板
_templates/autosummary/package.rst
:
1 | {{ fullname | escape | underline }} |
之后你就可以愉快的玩耍了.
如果你有疑问,可以看这个项目: https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html .
配置:
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/conf.py .
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/api.rst .
效果
https://pybind11-openke.readthedocs.io/zh_CN/latest/api.html .
链接到其他常用文档
官方教程: https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx .
链接到常用文档 (conf.py
):
1 | intersphinx_mapping = { |
忽略未安装模块
文档部署到 Read the Docs,是不可能安装 numpy
等包的,但是不安装这些包,当构建文档时会报错,那该怎么办呢,我们可以忽略模块 (conf.py
):
1 | autodoc_mock_imports = ["base", "torch", "numpy", "tqdm", "sklearn"] |
增加拷贝按钮
源项目地址:
- 安装 (如果文档部署在 Read the Docs, 记得在
requirements.txt
文件增加该包名):
1 | pip install sphinx-copybutton |
- 配置 (
conf.py
):
1 | extensions = [ |
查看源码
官方教程: https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html .
- 配置 (
conf.py
):
1 | extensions = [ |
效果:
自动为例子生成文档
插件项目地址: https://github.com/sphinx-gallery/sphinx-gallery .
插件文档地址: https://sphinx-gallery.github.io/stable/index.html .
源教程地址: https://sphinx-gallery.github.io/stable/getting_started.html .
- 项目结构:
1 | . |
-
我们想为 examples 中脚本自动生成文档,像 pytorch 官方教程中的快速开始的例子一样,pytorch 也是用这个插件自动为对应的脚本生成文档的。我们可以仿照 pytoch 官网的例子书写脚本注释来生成文档。
-
在
examples
目录下至少要有一个名为README.txt
或README.rst
的用作欢迎页的文件,语法为reST
。只是要有一个标题,例子如下:
1 | This is my gallery |
- 安装 (如果文档部署在 Read the Docs, 记得在
requirements.txt
文件增加该包名):
1 | pip install sphinx-gallery |
- 配置 (
conf.py
):
1 | extensions = [ |
- 引用:
1 | .. toctree:: |
如果你有疑问,可以看这个项目: https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html .
配置:
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/tree/pybind11-OpenKE-PyTorch/pybind11_ke_examples .
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/conf.py .
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/index.rst .
效果
https://pybind11-openke.readthedocs.io/zh_CN/latest/auto_examples/train_rescal_FB15K237.html .
交叉引用
引用另一个 rst 文档
1 | :doc:`installation` |
installation 是另一 rst 文档的文件名,效果:
-
https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/index.rst
-
https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html
引用另一个类
1 | :py:class:`pybind11_ke.module.strategy.NegativeSampling` |
pybind11_ke.module.strategy.NegativeSampling
是另一个类名,效果:
-
https://pybind11-openke.readthedocs.io/zh_CN/latest/_modules/pybind11_ke/config/Trainer.html#Trainer
引用类的方法
1 | :py:meth:`__init__` |
__init__
是方法,效果:
-
https://pybind11-openke.readthedocs.io/zh_CN/latest/_modules/pybind11_ke/config/Trainer.html#Trainer
引用类的属性
1 | :py:attr:`data_loader` |
data_loader
是属性,效果:
-
https://pybind11-openke.readthedocs.io/zh_CN/latest/_modules/pybind11_ke/config/Trainer.html#Trainer
类定义中注释
效果:
警告
源教程地址:
1 | .. Attention:: Directives at large. |
代码
终端
1 | .. code-block:: console |
效果:
python
1 | .. code-block:: python |
效果:
我的项目
我有两个项目应用了 Sphinx
。分别为:
-
https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html .
-
https://susu-sphinx-notes.readthedocs.io/en/latest/index.html .
结语
第六十八篇博文写完,开心!!!!
今天,也是充满希望的一天。