<p>当源代码位于<code>src</code>目录(如<code>Project/src</code>)中,而不是仅仅位于<code>Project</code>基本目录中时,这是“入门”的常用“规范方法”。</strong></p>
<p>遵循以下步骤:</p>
<ol>
<li><p>在<code>Project</code>目录中创建一个<code>docs</code>目录(从该<code>docs</code>目录执行以下步骤中的命令)</p>
</li>
<li><p><code>sphinx-quickstart</code>(从<code>build</code>中选择分开的<code>source</code>。将<code>.html</code>和<code>.rst</code>文件放在不同的文件夹中)</p>
</li>
<li><p><code>sphinx-apidoc -o ./source ../src</code></p>
</li>
<li><p><code>make html</code></p>
</li>
</ol>
<p>这将产生以下结构(前提是<code>.py</code>源文件位于<code>Project/src</code>):</p>
<pre><code>Project
|
├───docs
│ │ make.bat
│ │ Makefile
│ │
│ ├───build
│ └───source
│ │ conf.py
│ │ index.rst
│ │ modules.rst
│ │ stack.rst
│ │
│ ├───_static
│ └───_templates
└───src
stack.py
</code></pre>
<p>在<code>conf.py</code>中,您要添加(在步骤2之后):</p>
<pre class="lang-py prettyprint-override"><code>import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src')))
</code></pre>
<p>也包括在{<cd16>}中:</p>
<p><code>extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']</code></p>
<p>在{<cd19>}中,您可以链接{<cd20>}:</p>
<pre><code>Welcome to Project's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
</code></pre>
<p>您的<code>stack.rst</code>和<code>modules.rst</code>是由<code>sphinx-apidoc</code>自动生成的,此时无需更改它们。但你要知道这就是它们的样子:</p>
<p><code>stack.rst</code>:</p>
<pre><code>stack module
============
.. automodule:: stack
:members:
:undoc-members:
:show-inheritance:
</code></pre>
<p><code>modules.rst</code>:</p>
<pre><code>src
===
.. toctree::
:maxdepth: 4
stack
</code></pre>
<hr/>
<hr/>
在浏览器中“make html”打开“Project/docs/build/index.html”后,结果如下:
<p><a href="https://i.stack.imgur.com/SsElg.png" rel="noreferrer"><img src="https://i.stack.imgur.com/SsElg.png" alt="enter image description here"/></a></p>
<p>以及:</p>
<p><a href="https://i.stack.imgur.com/C9707.jpg" rel="noreferrer"><img src="https://i.stack.imgur.com/C9707.jpg" alt="enter image description here"/></a></p>