时间戳

首页 > 解决方案 > 通过在部分中附加各种注释来混合代码文档和代码？

python - 通过在部分中附加各种注释来混合代码文档和代码？

问题描述

考虑以下最小示例：

docs/index.rst

* :ref:`modindex`

docs/modules.rst

exampleproject
==============

.. toctree::
   :maxdepth: 4

   exampleproject

.. print_notes_attached_to_topic::
   :topic: notes_about_someproblem

docs/conf.py

extensions = ['sphinx.ext.autodoc']

docs/exampleproject.rst

exampleproject package
======================

Module contents
---------------

.. automodule:: exampleproject
   :members:
   :undoc-members:
   :show-inheritance:

exampleproject/__init__.py

def example_fun():
    """
    This is the docstring I'll be discussing.
    .. attach_to_topic::
       :topic: notes_about_someproblem
       
       Grass is green.
    """
    pass

def other_example_fun():
    """
    This is the second docstring I'll be discussing.
    .. attach_to_topic::
       :topic: notes_about_someproblem
       
       Sky is blue.
    """
    pass

我知道sphinx.ext.autodoc可以提取文档字符串并将它们放在 docs/exampleproject.rst 中。我的问题是：有没有办法自动将某些部分附加到特定文档？理想情况下，我想将尽可能多的文档放在源代码中，然后使用文档的源文件将这些信息按线性顺序排列。就像是：

  1. 在 example_fun 文档字符串中exampleproject/__init__.py，编写表达式“向名为 building_methods 的部分/主题添加注释，说‘在运行项目之前，做 xyz’”
  2. 在 index.rst 中，“列出与名为 building_methods 的部分/主题相关的所有注释”。

与自动文档的比较

我知道 sphinxsphinx.ext.autodoc可以处理应用程序的文档字符串。问题是 autodoc 强制文档的某种“代码优先”/“API 优先”结构。我正在寻找一种解决方案，它可以让我在代码中保留尽可能多的文档，然后将此文档转换为线性文档，其中包含从示例attach_to_topic指令之类的内容中提取的某些主题的数据。

狮身人面像有可能吗？

标签： pythondocumentationpython-sphinxdocumentation-generationcode-documentation

解决方案

我同意 mzjn 的观点，即您的示例并没有给出太多内容，但我会冒险进行一些猜测：

附加到 apidoc 存根页面

和存根文件由sphinx-apidocdocs/exampleproject.rst自动生成。然后您手动将您自己的内容（指令）附加到这些内容中。docs/modules.rst.. print_notes_attached_to_topic::

这将是有问题的，因为每次sphinx-apidoc提取 Python 文档字符串以重建其存根页面时，您的块都会被覆盖/丢失。我永远不会尝试将我自己的内容混合到由扩展程序拥有/生成的页面中 - 它们可以并排放置，但可以分开，例如将所有指令放在一个./docs/all-my-print-notes.rst页面中。

也就是说，如果你想让你的生活复杂化，那就进行后期处理。修改 Sphinx生成文件以检测存根页面更改并触发 Bash 或 Python 脚本，最终将您的自定义内容扑通一声。如果间接完成，则最干净——一个包含指令进入存根页面，以便您的自定义内容可以在其他地方保持隔离。

和(in & )的Jinja2 模板提供有限的自定义，但实际上只适用于布局和静态内容。autodocautosummary./site-packages/sphinx/templates/apidoc/./site-packages/sphinx/ext/autosummary/templates/

你的狮身人面像扩展

您想要的功能听起来很像sphinx.ext.todo。您的.. attach_to_topic::指令分散在整个 Python 模块文档字符串（相当于.. todo::指令）中，并且您的.. print_notes_attached_to_topic::指令将这些块收集成“线性顺序”（相当于.. todolist::）。

幸运的是，关于创建扩展的文档给出了这个例子，你可以根据自己的需要进行调整。您的扩展将有一个额外的功能，因为它提供了一个:topic:选项来标记/分类每个.. todo::项目，并限制每个.. todolist::排序规则的范围。

推荐阅读