sphinx 文档：sphinx 根目录之外的 .py 文件

Posted 2023-02-19

【中文标题】sphinx 文档：sphinx 根目录之外的 .py 文件

【英文标题】：sphinx documenting: .py file outside of the sphinx root

【发布时间】：2021-11-06 09:21:54

【问题描述】：

我需要一些关于 sphinx 文档生成器的帮助 我的 git 仓库看起来像这样：

根：

文档（用于狮身人面像的东西） 代码（用于 micropython 的东西） 问题是 spinx 并不能真正使用根目录之外的文件。 但没问题（我想，在深入研究***主题之后） 我创建了一个 boot_link.rst 文件，如下所示。 （我需要添加标题，否则不会生成。）

.. include:: ../../repo/boot.py

Boot file
==========

我在 index.rst 中的目录树看起来像这样：

.. toctree::
   :maxdepth: 2
   :caption: source code:
   
   Boot file <boot_link.rst>

现在 Spinx 可以读取我的 boot.py 文件，但它完全是一团糟。 启动页面如下所示：

首先是源代码，原样（所以代码在那里，还有每条评论，基本上是 .py 文件中的每一个字符，只是转储到那里） 然后是引导文件的标题。 :D 我可以得到一些帮助如何解决它吗？ 最终结果应该是一个基于 boot.py 文件的 cmets 的漂亮格式化页面。 （我的仓库中的其余文件也在稍后，用于）

【问题讨论】：

include 没有定义为你想要的，docutils.sourceforge.io/docs/ref/rst/directives.html#include

试试literalinclude指令？

要从 Python 代码中提取文档字符串，需要使用 autodoc 扩展：sphinx-doc.org/en/master/usage/extensions/autodoc.html。

literalinclude 不会削减它，我认为，根据描述：“通过将示例文本存储在 仅包含纯文本的外部文件，可以包括更长的逐字文本显示>. 我试过了，结果是 sphinx 将整个 .py 文件放入一个灰色的矩形/文本气泡中。代码已格式化并突出显示，但仍然包含实际代码，而不仅仅是注释。问题与autodoc 是它试图运行我的代码。甚至 boot.py 也会导致各种错误，因为它是基于 micropyton 代码的，不适合在 pc 上运行。

【参考方案1】：

编辑：好的，我找到了解决方案。将此添加到 index.rst：

.. toctree::
   :maxdepth: 2
   :caption: source code:
   
   autodoc

将此添加到 conf.py

import os
import sys

sys.path.insert(0, os.path.abspath('../../repo/'))

还有这个：

extensions = ['sphinx.ext.autodoc']

最后像这样创建 autodoc.rst：

.. _autodoc:
 
.. contents::
 
something.py
=================
 
.. automodule:: something
  :members:
  :undoc-members:
  
  
something1.py
=================
 
.. automodule:: something1
  :members:
  :undoc-members:
  
  
something2.py
=================
 
.. automodule:: something2
  :members:
  :undoc-members:

我想就是这样。