00068 Sphinx 杂项

Python
杂项
发布日期:   2023-05-29
更新日期:   2024-12-28

前言

Sphinx 是一个能自动生成文档的工具，主要用于 Python 语言。

官网: https://www.sphinx-doc.org/en/master/ 。

其中下面三个著名工具网站就是应用它来生成文档的。

  1. python: https://docs.python.org/3/ .

  2. NumPy: https://numpy.org/doc/stable/ .

  3. Pytorch: https://pytorch.org/docs/stable/index.html .

操作系统：Ubuntu 20.04.4 LTS

参考文档

  1. pybind11-OpenKE

  2. sphinx-autopackagesummary

  3. Cross-referencing Python objects

学习路线

  1. 首先学习如何部署到 Read the Docs，可以看 Read the Docs 的官方教程。

  2. 然后学习一个非常好的学习例子。

  3. 之后学习 Read the Docs 设计的主题的教程。

  4. 最后学习 Sphinx官方教程。

插件 - sphinx-autopackagesummary

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

该插件弥补了 sphinx 内置的 autosummary 指令不能处理深层嵌套的问题。

再也不用这样生成 API 文档了。

.. autosummary::
   :toctree: _autosummary

   mypackage.submodule1
   mypackage.submodule2
   mypackage.submodule3

仅仅这样写就可以了。

.. autopackagesummary:: mypackage
   :toctree: _autosummary

安装

  1. 安装 (如果文档部署在 Read the Docs, 记得在 requirements.txt 文件增加该包名):
pip install sphinx-autopackagesummary
  1. 在 conf.py 中开启它.
extensions = ['sphinx.ext.autosummary', 'sphinx_autopackagesummary']

autosummary_generate = True

使用

  1. 如果您的包有子包，则可以通过自定义 autosummary 模板来递归地使用它。例如，您可以将根包记录如下：
.. autopackagesummary:: mypackage
   :toctree: _autosummary
   :template: autosummary/package.rst
  1. 创建一个模板 _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 .

配置:

  1. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/requirements.txt .

  2. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/conf.py .

  3. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/api.rst .

  4. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/_templates/autosummary/package.rst .

效果

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):

autodoc_mock_imports = ["base", "torch", "numpy", "tqdm", "sklearn"]

增加拷贝按钮

源项目地址:

  1. https://pypi.org/project/sphinx-copybutton/ .

  2. https://github.com/executablebooks/sphinx-copybutton .

  1. 安装 (如果文档部署在 Read the Docs, 记得在 requirements.txt 文件增加该包名):
pip install sphinx-copybutton
  1. 配置 (conf.py):
extensions = [
    ...
    'sphinx_copybutton'
    ...
]

查看源码

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

  1. 配置 (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 .

  1. 项目结构:
.
├── 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)

  1. 我们想为 examples 中脚本自动生成文档，像 pytorch 官方教程中的快速开始的例子一样，pytorch 也是用这个插件自动为对应的脚本生成文档的。我们可以仿照 pytoch 官网的例子书写脚本注释来生成文档。

  2. 在 examples 目录下至少要有一个名为 README.txt 或 README.rst 的用作欢迎页的文件，语法为 reST。只是要有一个标题，例子如下:

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

Below is a gallery of examples
  1. 安装 (如果文档部署在 Read the Docs, 记得在 requirements.txt 文件增加该包名):
pip install sphinx-gallery
  1. 配置 (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
}
  1. 引用:
.. 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 .

配置:

  1. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/requirements.txt .

  2. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/tree/pybind11-OpenKE-PyTorch/pybind11_ke_examples .

  3. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/conf.py .

  4. 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 .

交叉引用

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

引用另一个 rst 文档

:doc:`installation`

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

引用另一个类

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

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

引用类的方法

:py:meth:`__init__`

__init__ 是方法，效果:

引用类的属性

:py:attr:`data_loader`

data_loader 是属性，效果:

类定义中注释

效果:

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

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

  3. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/docs/reference/module/model/TransE.rst

警告

源教程地址:

  1. https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions .

  2. https://raw.githubusercontent.com/readthedocs/sphinx_rtd_theme/72691f502500c8fc0c0d22422d0919bc628ddf5f/docs/demo/demo.rst

.. 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

效果:

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

  2. https://raw.githubusercontent.com/LuYF-Lemon-love/pybind11-OpenKE/pybind11-OpenKE-PyTorch/docs/installation.rst

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)

效果:

  1. https://pybind11-openke.readthedocs.io/zh_CN/latest/reference/data/TestDataLoader.html

  2. https://github.com/LuYF-Lemon-love/pybind11-OpenKE/blob/pybind11-OpenKE-PyTorch/pybind11_ke/data/TestDataLoader.py

我的项目

我有两个项目应用了 Sphinx。分别为:

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

  2. https://susu-sphinx-notes.readthedocs.io/en/latest/index.html .

结语

第六十八篇博文写完，开心！！！！

今天，也是充满希望的一天。

文章作者: LuYF-Lemon-love
文章链接: https://luyf-lemon-love.space/2023/05/29/00068-sphinx-za-xiang/
版权声明: 本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 LuYF-Lemon-love !
Python
赏
  目录