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 文档了。

.. autosummary::
   :toctree: _autosummary

   mypackage.submodule1
   mypackage.submodule2
   mypackage.submodule3

仅仅这样写就可以了。

1 2	.. autopackagesummary:: mypackage :toctree: _autosummary

安装

安装 (如果文档部署在 Read the Docs, 记得在 requirements.txt 文件增加该包名):

1	pip install sphinx-autopackagesummary

在 conf.py 中开启它.

1
2
3

extensions = ['sphinx.ext.autosummary', 'sphinx_autopackagesummary']

autosummary_generate = True

使用

如果您的包有子包，则可以通过自定义 autosummary 模板来递归地使用它。例如，您可以将根包记录如下：

1
2
3

.. autopackagesummary:: mypackage
   :toctree: _autosummary
   :template: autosummary/package.rst

创建一个模板 _templates/autosummary/package.rst:

{{ fullname | escape | underline }}

.. automodule:: {{ fullname }}

   .. autopackagesummary:: {{ fullname }}
      :toctree: .
      :template: autosummary/package.rst

之后你就可以愉快的玩耍了.

如果你有疑问，可以看这个项目: https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html .

配置:

效果

https://pybind11-openke.readthedocs.io/zh_CN/latest/api.html .

链接到其他常用文档

官方教程: https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx .

链接到常用文档 (conf.py):

intersphinx_mapping = {
    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
    "python": ("https://docs.python.org/3/", None),
    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
    "torch": ("https://pytorch.org/docs/stable/", None),
    'numpy': ('https://numpy.org/doc/stable', None),
}

忽略未安装模块

文档部署到 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):

extensions = [
    ...
    'sphinx_copybutton'
    ...
]

查看源码

官方教程: https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html .

配置 (conf.py):

extensions = [
    ...
    'sphinx.ext.viewcode'
    ...
]

效果:

https://pybind11-openke.readthedocs.io/zh_CN/latest/reference/module/model/TransE.html#pybind11_ke.module.model.TransE

自动为例子生成文档

插件项目地址: https://github.com/sphinx-gallery/sphinx-gallery .

插件文档地址: https://sphinx-gallery.github.io/stable/index.html .

源教程地址: https://sphinx-gallery.github.io/stable/getting_started.html .

项目结构:

.
├── doc
│   ├── conf.py
│   ├── index.rst
|   ├── make.bat
│   └── Makefile
├── my_python_module
│   ├── __init__.py
│   └── mod.py
└── examples
    ├── plot_example.py
    ├── example.py
    └── README.txt (or .rst)

我们想为 examples 中脚本自动生成文档，像 pytorch 官方教程中的快速开始的例子一样，pytorch 也是用这个插件自动为对应的脚本生成文档的。我们可以仿照 pytoch 官网的例子书写脚本注释来生成文档。
在 examples 目录下至少要有一个名为 README.txt 或 README.rst 的用作欢迎页的文件，语法为 reST。只是要有一个标题，例子如下:

This is my gallery
==================

Below is a gallery of examples

安装 (如果文档部署在 Read the Docs, 记得在 requirements.txt 文件增加该包名):

1	pip install sphinx-gallery

配置 (conf.py):

extensions = [
    ...
    'sphinx_gallery.gen_gallery',
    ]

sphinx_gallery_conf = {
     'examples_dirs': '../examples',   # path to your example scripts
     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
}

引用:

.. toctree::
   :maxdepth: 2
   :hidden:
   :includehidden:
   :caption: 例子

   auto_examples/index
   auto_examples/train_rescal_FB15K237
   auto_examples/train_transe_FB15K237

如果你有疑问，可以看这个项目: https://pybind11-openke.readthedocs.io/zh_CN/latest/index.html .

配置:

效果

https://pybind11-openke.readthedocs.io/zh_CN/latest/auto_examples/train_rescal_FB15K237.html .

交叉引用

官方文档地址: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects .

引用另一个 rst 文档

1	:doc:`installation`

installation 是另一 rst 文档的文件名，效果:

引用另一个类

1	:py:class:`pybind11_ke.module.strategy.NegativeSampling`

pybind11_ke.module.strategy.NegativeSampling 是另一个类名，效果:

引用类的方法

1	:py:meth:`__init__`

__init__ 是方法，效果:

引用类的属性

1	:py:attr:`data_loader`

data_loader 是属性，效果:

类定义中注释

效果:

警告

源教程地址:

.. Attention:: Directives at large.

.. Caution:: Don't take any wooden nickels.

.. DANGER:: Mad scientist at work!

.. Error:: Does not compute.

.. Hint:: It's bigger than a bread box.

.. Important::
   - Wash behind your ears.
   - Clean up your room.

     - Including the closet.
     - The bathroom too.

       - Take the trash out of the bathroom.
       - Clean the sink.
   - Call your mother.
   - Back up your data.

.. Note:: This is a note.
   Equations within a note:
   :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu}  + \rho_\Lambda g_{\mu\nu})`.

.. Tip:: 15% if the service is good.

    +---------+
    | Example |
    +=========+
    | Thing1  |
    +---------+
    | Thing2  |
    +---------+
    | Thing3  |
    +---------+

.. WARNING:: Strong prose may provoke extreme mental exertion.
   Reader discretion is strongly advised.

.. admonition:: And, by the way...

   You can make up your own admonition too.

代码

终端

.. code-block:: console

    $ conda create --name pybind11-ke python=3.10 -y
    $ conda activate pybind11-ke
    $ pip install torch -i https://pypi.tuna.tsinghua.edu.cn/simple
    $ pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple
    $ pip install tqdm -i https://pypi.tuna.tsinghua.edu.cn/simple
    $ pip install scikit-learn -i https://pypi.tuna.tsinghua.edu.cn/simple

效果:

python

.. code-block:: python

	from pybind11_ke.config import Tester
	from pybind11_ke.data import TestDataLoader

	# dataloader for test
	test_dataloader = TestDataLoader("./benchmarks/FB15K237/", "link")

	# test the model
	tester = Tester(model = transe, data_loader = test_dataloader, use_gpu = True)

效果: