sphinx 项目根目录

I recently visited a company where I had a nice talk with one of its employees. We talked about technology and programming. Then we touched the subject of project documentation. Specifically how React does it automatically but Django doesn’t. That made me think I should do some automatic documentation for my Django projects.

我最近访问了一家公司，在那里我与其中一名员工进行了愉快的交谈。 我们讨论了技术和编程。 然后，我们触及了项目文档的主题。 具体来说，React是如何自动执行的，而Django没有。 那使我认为我应该为Django项目做一些自动文档。

I couldn’t find any relevant documentation on how its done, so it took me a little longer than I originally planned. Not because it was hard, but because I found that the Sphinx official documentation and other resources to be outdated or obscure.

我找不到有关其完成方式的任何相关文档，因此它花了我的时间比我最初计划的要长。 不是因为很难，而是因为我发现Sphinx官方文档和其他资源已经过时或晦涩。

So today I have made a simple but comprehensive tutorial that explains how to make Django documentation using the Sphinx documentation tool in Ubuntu.

因此，今天我做了一个简单而全面的教程，解释了如何在Ubuntu中使用Sphinx文档工具制作Django文档。

安装Sphinx (Install Sphinx)

First you should enter the virtual environment for your Django project.

首先，您应该为Django项目输入虚拟环境。

Installing Sphinx is quite straightforward using pip3 (pip for Python 3):

使用pip3(适用于Python 3的pip)安装Sphinx非常简单：

pip3 install sphinx

创建文档目录 (Create a documentation directory)

Once you’ve installed Sphinx, you will need to create the document root folder. This folder will hold your documentation and other files you will need (images, about pages, and so on…).

一旦安装了Sphinx，就需要创建文档根文件夹。 该文件夹将保存您的文档和其他所需文件(图像，有关页面的信息，等等)。

Create your document root folder in your project main folder and name it /docs.

在项目主文件夹中创建文档根文件夹，并将其命名为/ docs。

To start Sphinx, run this command inside your /docs folder:

要启动Sphinx，请在/ docs文件夹中运行以下命令：

sphinx-quickstart

You’ll have a lot of options now. In most cases you can simply retype the default option, but there are some options you need to pay attention to.

您现在将有很多选择。 在大多数情况下，您可以简单地重新输入默认选项，但是您需要注意一些选项。

This is how I answered:

这就是我的回答：

Welcome to the Sphinx 1.7.5 quickstart utility.Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).Selected root path: .You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.> Separate source and build directories (y/n) [n]: nInside the root directory, two more directories will be created; “_templates”
for custom HTML templates and “_static” for custom stylesheets and other static
files. You can enter another prefix (such as “.”) to replace the underscore.> Name prefix for templates and static dir [_]: _The project name will occur in several places in the built documentation.
> Project name: Your_project_name
> Author name(s): Goran Aviani
> Project release []: 1.0If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.> Project language [en]: enThe file name suffix for source files. Commonly, this is either “.txt”
or “.rst”. Only files with this suffix are considered documents.> Source file suffix [.rst]: .rstOne document is special in that it is considered the top node of the
“contents tree”, that is, it is the root of the hierarchical structure
of the documents. Normally, this is “index”, but if your “index”
document is a custom template, you can also set this to another filename.> Name of your master document (without suffix) [index]: indexSphinx can also add configuration for epub output:> Do you want to use the epub builder (y/n) [n]: nIndicate which of the following Sphinx extensions should be enabled:> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: yCreating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.Finished: An initial directory structure has been created.You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:make builderwhere “builder” is one of the supported builders, e.g. html, latex or linkcheck.

Django连接 (Django connection)

In your project folder, find /docs/conf.py and inside it, somewhere near the top of the file, find “#import os”. Just below it, write this:

在您的项目文件夹中，找到/docs/conf.py，并在其中的文件顶部附近找到“ #import os”。 在它的正下方，写下：

import os
import sys
import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'Your_project_name.settings'
django.setup()

Now there are two ways you can proceed:

现在，有两种方法可以继续：

1. You can use sphinx-apidoc to generate completely automatic documentation, or

   您可以使用sphinx-apidoc 生成全自动文档，或者

2. You can build your own modules that will show in the documentation.您可以构建自己的模块，这些模块将显示在文档中。

In this tutorial I am going to show you how to do it both ways.

在本教程中，我将向您展示两种方法。

1. Sphinx-apidoc (1. Sphinx-apidoc)

This is the simpler method where you just need to navigate to your /docs folder and execute:

这是更简单的方法，您只需要导航到/ docs文件夹并执行：

sphinx-apidoc -o . ..

Now you need to build your documentation by running the command:

现在，您需要通过运行以下命令来构建文档：

make html

Navigate to Your_project_folder/docs/_build/html and open index.html. This is the index page of your documentation.

导航到Your_project_folder / docs / _build / html并打开index.html。 这是文档的索引页。

2.构建自己的模块 (2. Building your own modules)

This is the slightly more complicated way, but will give you much more freedom in organizing your documentation.

这是稍微复杂一些的方法，但是会给您更多的组织文档的自由。

Now you’ll want to make documentation about your views, modules etc. But first let me show you an easy example, just so you understand the logic of this part:

现在，您将要制作有关视图，模块等的文档。但是，首先让我向您展示一个简单的示例，以使您了解这部分的逻辑：

Go in your /docs folder and create a new folder named “/modules”. Inside it create a file named all-about-me.rst:

进入/ docs文件夹并创建一个名为“ / modules”的新文件夹。 在其中创建一个名为all-about-me.rst的文件：

mkdir modulesf
touch modules/all-about-me.rst

Inside all-about-me.rst write something like this:

在all-about-me.rst内编写如下内容：

############
All about me
############I’m Goran Aviani, a Django developer.

Now you’ve created something to show in your documentation, but still you don’t have an actual place to show it. Go back to the /docs folder and open index.rst and just bellow this code

现在，您已经创建了一些要显示在文档中的内容，但是仍然没有显示它的实际位置。 返回到/ docs文件夹并打开index.rst，然后将以下代码显示如下

.. toctree:::maxdepth: 2:caption: Contents:

Add this:

添加：

modules/all-about-me.rst

Make it so there is a blank line between the upper code and the added line:

使其在上方代码和添加的行之间留空行：

.. toctree:::maxdepth: 2:caption: Contents:modules/all-about-me.rst

Now you need to build your documentation. Change the location to the folder that contains the Makefile ( that is the /docs folder). Then run in the terminal:

现在，您需要构建文档。 将位置更改为包含Makefile的文件夹(即/ docs文件夹)。 然后在终端中运行：

make html

You will find your documentation in

您可以在以下位置找到文档

Your_project_folder/docs/_build/html and open index.html

Your_project_folder / docs / _build / html并打开index.html

You can do the same for your Django views:

您可以对Django视图执行相同的操作：

Inside the /modules folder, create the views.rst file.

在/ modules文件夹中，创建views.rst文件。

touch views.rst

Inside the views.rst file write this:

在views.rst文件中写入以下内容：

Views
======.. automodule:: yourapp.views:members::undoc-members:

Inside index.rst, just under modules/all-about-me.rst, add this:

在index.rst内部，在modules / all-about-me.rst下，添加以下代码：

modules/views.rst

Now you again need to build your documentation by running “make html” inside your /docs folder:

现在，您再次需要通过在/ docs文件夹中运行“ make html”来构建文档：

make html

Get the idea? First you create the .rst file and then you put it inside index.rst so it can be displayed on index.html page.

有主意吗？ 首先，您创建.rst文件，然后将其放入index.rst中，以便可以在index.html页面上显示它。

You can make same thing for your models. Go in your /modules folder and create models.rst file.

您可以为模型制作相同的东西。 进入/ modules文件夹并创建models.rst文件。

touch models.rst

You can add something like this in your models.rst file:

您可以在models.rst文件中添加以下内容：

Models
=======.. automodule:: yourapp.models:members::undoc-members:

Inside index.rst just under modules/views.rst paste:

在index.rst内部，就在modules / views.rst下面，粘贴：

modules/models.rst

Inside your /docs folder run:

在/ docs文件夹中运行：

make html

文件测试 (Documentation test)

You can test your documentation by running this code inside your /docs folder:

您可以通过在/ docs文件夹中运行以下代码来测试文档：

make linkcheck

Voilà! You are done!

瞧！ 大功告成！

This is my first public tutorial, so give me a few claps if you like it :)

这是我的第一个公开教程，如果您喜欢，请给我一些鼓掌:)

Thank you for reading! Check out more articles like this on my freeCodeCamp profile: https://www.freecodecamp.org/news/author/goran/ and other fun stuff I build on my GitHub page: https://github.com/GoranAviani

感谢您的阅读！ 在我的freeCodeCamp个人资料上查看更多类似的文章： https ://www.freecodecamp.org/news/author/goran/和我在GitHub页面上构建的其他有趣的东西： https : //github.com/GoranAviani

翻译自: https://www.freecodecamp.org/news/sphinx-for-django-documentation-2454e924b3bc/

sphinx 项目根目录