将函数文档嵌入到 sphinx 的页面中
我有一个中型 python 项目，目前正在使用 sphinx 和 autodoc 扩展来记录该项目。我已经掌握了基础知识，生成的文档看起来很合理。
我现在遇到了一个有趣的文档问题：我有一些 JSON 输入文件，其中包含某种配置。它包含在我的应用程序的不同部分中使用的几个部分。我认为保持文档最新的最佳方法是尽可能接近其使用点来记录配置选项。
另一方面，我真的希望有一个页面来描述完整的输入文件结构。
我想如果我能以某种方式将相关文档块“嵌入”到此页面中，以便它同时显示在该页面和相应的模块文档页面中，如下所示：
a.py:
def fn_using_A():
'''documentation for config parameter paramA
'''
pass
b.py
def fn_using_B():
'''documentation for config parameter paramB
'''
输入文件格式文档页面应该看起来有点像这样：
paramB
------
documentation for config parameter paramB
paramA
------
documentation for config parameter paramA
我不想有相应功能/模块/任何内容的链接/引用，而是文档的逐字副本，而不必实际将文档复制到相应的 .rst 文件中。
最好只包含我可以在代码文档中以某种方式标记的文档的一部分。
我尝试使用 reST 的替换功能，
def fn_handling_C():
'''fn documentation
.. |paramC_documentation| replace:: foo bar baz
'''
在我的代码中编写并在记录我的输入文件格式的 .rst 文件中使用 |paramC_documentation| ，但生成文档会产生一条错误消息，大意是替换模式未知。这并不令我感到惊讶，因为 autodoc 不会为与手动编写的 .rst 文件一起解析的模块生成完整的 .rst 文件。
有没有办法用 sphinx 来实现这一点？
I have a medium-sized python project that I'm currently documenting using sphinx with the autodoc extension. I have the basics down, the generated documentation looks reasonable.
I have now come across an interesting documentation problem: I have some JSON input file that contains configuration of some sorts. It contains several sections that are used in different parts of my application. I figured the best way to keep the documentation up to date is to document configuration options as close to the point of their usage as possible.
On the other hand, I'd really like to have a single page describing the complete input file structure.
I figured it would be nice if I could somehow "transclude" the relevant documentation blocks into this page so that it shows up both in this page and within the respective module documentation pages like so:
a.py:
def fn_using_A():
'''documentation for config parameter paramA
'''
pass
b.py
def fn_using_B():
'''documentation for config parameter paramB
'''
The input file format documentation page should look somewhat like this:
paramB
------
documentation for config parameter paramB
paramA
------
documentation for config parameter paramA
I would like to not have links/references to the respective functions/modules/whatever but a verbatim copy of the documentation without having to actually copy the documentation into the respective .rst file.
It would be even better to only transclude a part of the documentation I can mark somehow within my code documentation.
I tried using reST's replace feature, writing
def fn_handling_C():
'''fn documentation
.. |paramC_documentation| replace:: foo bar baz
'''
in my code and using |paramC_documentation| within the .rst file that documents my input file format, but generating the documentation yields an error message to the effect that the replacement pattern isn't known. That doesn't surprise me since autodoc doesn't generate full .rst files for modules which are parsed together with manually written .rst files.
Is there a way to achieve this with sphinx?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
我最终编写了自己的 sphinx 扩展。我使用 sphinx-todo 作为基础并根据我的喜好进行修改。
I ended up writing my own sphinx extension. I used sphinx-todo as basis and modified that to my liking.