用狮身人面像制作文件

Communication is one of the most important skills in Engineering. Writing clear code is core, and writing good documentation is the cherry on the cake. In this article we’ll see how to use Sphinx to produce an html documentation for your project. We will cover basic configuration

çommunication是在工程中最重要的技能之一。 编写清晰的代码是核心，而编写良好的文档则至关重要。 在本文中，我们将看到如何使用Sphinx为您的项目生成html文档。 我们将介绍基本配置

狮身人面像 (Sphinx)

Sphinx is one of many tools that enable you to convert code documentation into another format, hopefully more human friendly. Other alternatives are Doxygen, which would be recommended for C++. Sphinx can produce pdf, man pages and in the case of our demonstration, html pages. Sphinx uses rst (reStructuredText) or Markdown as a documentation writing language.

Sphinx是使您能够将代码文档转换为另一种格式的工具之一，希望它更人性化。 其他替代方法是Doxygen，建议将其用于C ++。 Sphinx可以生成pdf，手册页，在我们的演示中可以生成html页。 Sphinx使用rst(reStructuredText)或Markdown作为文档编写语言。

假设条件 (Assumptions)

I will consider that your project is mainly written in python, and is organized in the following way:

我将认为您的项目主要是用python编写的，并且组织方式如下：

a-project
|-a_project
  |-module_a
    |-a_sample_class_a.py
  |-module_b
    |-sample_class_b.py
|-setup.py
|-requirements.txt
|-Makefile
|-Readme.md

Additionally, both classes are already documented using rst.

此外，两个类都已使用rst进行了文档记录。

建立 (Set up)

Add sphinx and others to the requirements of your project:

将狮身人面像和其他添加到您的项目需求中：

# requirements.txtSphinx==3.2.1
sphinx-rtd-theme==0.5.0 # to use a nice modern theme
recommonmark==0.6.0 # to include the Readme.md

Install the requirements, for example using pip:

安装要求，例如使用pip：

pip install -r requirements.txt

I would recommend to add the above line in your Makefile, or to use the setup.py to install all dependencies.

我建议将上述行添加到您的Makefile中 ，或使用setup.py安装所有依赖项。

Let’s create the documentation folders and basic structure (again, add this to your Makefile to maintain max reproducibility of your code) :

让我们创建文档文件夹和基本结构(同样，将其添加到Makefile中，以保持代码的最大可重复性)：

mkdir -p docs
cd docs
sphinx-quickstart

You will be prompted with some questions about your project (name, author, version, etc.). The last step will create a couple of additional basic files for documentation generation.

系统将提示您有关项目的一些问题(名称，作者，版本等)。 最后一步将创建几个用于文档生成的其他基本文件。

a-project
...
|-docs
  |-build
  |-source
    |-_static
    |-_templates
    |-conf.py
    |-index.rst
  |-make.bat
  |-Makefile

If you are like me and use Makefile, you can remove the make.bat.

如果您像我一样使用Makefile ，则可以删除make.bat。

组态 (Configuration)

First let’s adjust the conf.py file. Uncomment the following lines.

首先让我们调整conf.py文件。 取消注释以下几行。

# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

Let’s add some practical packages, namely: autodoc which will semi-automatically add documentation pages; mathjax which will handle math expression display for html; sphinx_rtd_theme for the theme; and recommonmark to be able to use Markdown files:

让我们添加一些实用的软件包，即： autodoc ，它将半自动添加文档页面； mathjax将处理html的数学表达式显示； sphinx_rtd_theme为主题； 并重新标记以能够使用Markdown文件：

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax',
              'sphinx_rtd_theme', 'recommonmark',]

Let’s also change the theme, you can choose from many different options that you can personalize. I went with classic.

我们还要更改主题，您可以从许多可以个性化的选项中进行选择 。 我喜欢经典。

html_theme = 'sphinx_rtd_theme'

制作干净的文档 (Producing a clean looking documentation)

We would like to produce a clean looking doc, that will not be a one page recap of all our code. Therefore we are going to separate the documentation file for our different modules.

我们希望生成一个外观简洁的文档，而不是我们所有代码的一页摘要。 因此，我们将为不同模块分离文档文件。

First we will add two files in the docs folder.

首先，我们将在docs文件夹中添加两个文件。

a-project
|-docs
  |-build
  |-source
    |-_static
    |-_templates
    |-conf.py
    |-index.rst 
    |-module_a.rst
    |-module_b.rst 
  |-make.bat
  |-Makefile

You can fill in module_a.rst and module_b.rst in more or less the same way:

您可以大致相同的方式填写module_a.rst和module_b.rst：

# module_a.rstMODULE A
========
A module about a cumulative sum.
.. automodule:: a_project.module_a.sample_class_a
   :members:

Then modify your index.rst toctree.

然后修改index.rst toctree。

Welcome to a-project documentation!
==============================================
.. toctree::
   module_a
   module_b   :maxdepth: 2
   :caption: Contents:

This will add these two modules as part of the index and produce separate pages to read your documentation.

这会将这两个模块添加为索引的一部分，并产生单独的页面来阅读您的文档。

在文档中使用主要的自述文件 (Using the main Readme in the doc)

I will be honest with you, after looking around on the internet, the easiest solution I found was to copy the Readme.md inside the documentation folder and then add it to the index.rst.

老实说，在互联网上浏览后，我发现最简单的解决方案是将Readme.md复制到文档文件夹中，然后将其添加到index.rst。

Welcome to a_project's documentation!
=====================================
.. toctree::
   About <README.md>
   module_a
   module_b
   :maxdepth: 2
   :caption: Contents:

生成第一个文档 (Generating the first documentation)

Add the following lines to your root Makefile.

将以下行添加到您的根Makefile中。

doc:
   cp README.md docs/source/README.md
   cd docs && $(MAKE) html

And just build it.

并建立它。

Your build directory should contain an index.html that you can open in your browser.

您的构建目录应包含一个index.html ，您可以在浏览器中打开它。

结论 (Conclusion)

A github project demonstrating this documentation building is available for demonstration. Next steps would be not to use rst style to write docs. I would recommend Google or Numpy style, but for that you will need the napoleon extension. Another important point would be to use github pages / read the docs to publish your documentation. Which is important when you work on public repositories, not everyone wants to copy locally the repository and generate the documentation.

演示此文档构建的github项目可用于演示 。 下一步将不是使用rst样式编写文档。 我会推荐Google或Numpy风格，但为此，您需要napoleon扩展名 。 另一个重要的一点是使用github页面/阅读文档来发布您的文档。 在您使用公共存储库时，这很重要，并非所有人都希望在本地复制存储库并生成文档。

来源和有用的文档 (Sources and useful documentation)

• Sphinx

  狮身人面像

• Write the docs

  写文档

• Read the doc

  阅读文档

翻译自: https://medium.com/@l.mioulet/producing-documentation-with-sphinx-152642cbe40f