<p>让我们以一个项目为例:<a href="https://github.com/aakriti0fnu/dl4sci-school-2020" rel="nofollow noreferrer">^{<cd1>} on master branch</a>,<em><strong>提交:6cbcc2c72d5dc74d2defa56bf63706fd628d9892</strong></em>:</p>
<pre><code>├── dl4sci-school-2020
│ ├── LICENSE
│ ├── README.md
│ ├── src
│ │ └── __init__.py
│ └── utility
│ ├── __init__.py
│ └── utils.py
</code></pre>
<p>和<a href="https://github.com/aakriti0fnu/dl4sci-school-2020/blob/master/utility/utils.py" rel="nofollow noreferrer">utility package has a utils.py module</a>:</p>
<p><strong>遵循此过程(仅供参考,我正在使用斯芬克斯build 3.1.2</strong></em>):</p>
<ol>
<li>在项目下创建<code>docs/</code>目录:</li>
</ol>
<pre><code>mkdir docs
cd docs
</code></pre>
<ol start=“2”>
<li>在<code>docs/</code>内启动狮身人面像,只需传递<code>project_name</code>,<code>your_name</code>&<code>version</code>由您选择,其余保留默认值</李>
</ol>
<pre><code>sphinx-quickstart
</code></pre>
<p>您将在<code>docs/</code>文件夹中自动生成以下内容</p>
<pre><code>├── docs
│ ├── Makefile
│ ├── build
│ ├── make.bat
│ └── source
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ └── index.rst
</code></pre>
<p>因为,我们创建了一个单独的<code>docs</code>目录,所以需要sphinx查找
在哪里可以找到构建文件和python src模块。
因此,编辑conf.py文件,您也可以使用我的conf.py文件</p>
<pre><code>import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
sys.path.insert(0, basedir)
</code></pre>
<p>现在,要启用对嵌套多个包的访问&;如果有模块,则需要编辑<code>index.rst</code>文件</p>
<pre><code>.. toctree::
:maxdepth: 2
:caption: Description of my CodeBase:
modules
</code></pre>
<p><code>modules</code>从我们将在下面创建的<code>modules.rst</code>文件中拾取内容:
确保您仍然在<code>doc/</code>中运行下面的命令</p>
<pre><code>sphinx-apidoc -o ./source ..
</code></pre>
<p>您得到的输出:</p>
<pre><code>├── docs
│ ├── Makefile
│ ├── build
│ ├── make.bat
│ └── source
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ ├── index.rst
│ ├── modules.rst
│ ├── src.rst
│ └── utility.rst
</code></pre>
<p>现在运行:</p>
<pre><code>make html
</code></pre>
<p>现在,在您选择的浏览器中打开</p>
<p><code>file:///<absolute_path_to_your_project>/dl4sci-school-2020/docs/build/html/index.html</code></p>
<p><em><strong>您准备好漂亮的文档了吗</strong></em>
<a href="https://i.stack.imgur.com/uLJg7.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/uLJg7.png" alt="auto-generated python docs."/></a></p>
<p><a href="https://imgur.com/5t1uguh" rel="nofollow noreferrer">https://imgur.com/5t1uguh</a></p>
<p><em><strong>仅供参考,您可以切换您选择的任何主题,我发现<code>sphinx_rtd_theme</code>和扩展<code>sphinxcontrib.napoleon</code>超级毒品!。感谢他们的创造者,所以我使用了它。</strong></em></p>
<p>下面的工作</p>
<pre><code>pip install sphinxcontrib-napoleon
pip install sphinx-rtd-theme
</code></pre>
<p>您可以将文档托管在<a href="https://github.com/readthedocs/readthedocs.org" rel="nofollow noreferrer">readthedocs</a>
享受编写代码的乐趣</p>