sphinx_Sphinx之谜：如何轻松地编写代码

sphinx

为什么我在这里？ (Why Am I Here?)

You, the reader, are here because you wrote some awesome tool in Python, and you want to make it accessible and easy to use.

读者之所以在这里，是因为您使用Python编写了一些很棒的工具，并且希望使其易于使用。

I, the writer, am here because I was right where you are a few months ago. I wanted to use the Sphinx package to make a ReadTheDocs-style documentation for my project.

我(作家)之所以在这里是因为几个月前我就在您所在的位置。 我想使用Sphinx包为我的项目制作ReadTheDocs风格的文档。

I found the onboarding of Sphinx nontrivial, which is why I made this GitHub repo that can be used as a template for your project.

我发现Sphinx的入门很简单，这就是为什么我制作了这个GitHub存储库以用作您的项目模板的原因。

Before we start, some basic assumptions, to make sure we are on the same page:

在开始之前，请先进行一些基本假设，以确保我们位于同一页面上：

• You are writing in Python.
  您正在用Python编写。

• You wrote docstrings for the pieces of code you wish to document.

  您为要记录的代码段编写了文档字符串 。

• Your goal is to make a ReadTheDocs-style documentation that, at least partially, will automagically generate itself.

  您的目标是制作一个ReadTheDocs样式的文档，该文档至少部分将自动生成自身。

• You are aware that in 10 minutes you could publish the first version of your documentation, that is going to look something like this:

  您知道， 您可以在10分钟内发布文档的第一个版本 ，如下所示 ：

第1部分-设置舞台 (Part 1 - Setting the Stage)

• Install Sphinx: pip install sphinx

  安装Sphinx： pip install sphinx

• Go to github.com/DalyaG/Sphinx185:

  转到github.com/DalyaG/Sphinx185 ：

• Download the folder documentation_template_for_your_next_project

  下载文件夹documentation_template_for_your_next_project

• Copy to your project
  复制到您的项目

• Rename the folder documentation

  重命名文件夹documentation

第2部分-个性化 (Part 2 - Personalize)

• Open the file <your_project>/documentation/conf.py in your favorite editor. Search for the pattern #CHNAGEME# and follow the instructions.

  在您喜欢的编辑器中打开文件<your_project>/documentation/c conf.py。 搜索模式ttern #CHN AGEME＃，然后按照说明进行操作。

• Similarly, edit the file <your_project>/documentation/index.rst and follow the inline instructions.

  同样，编辑文件<your_project>/documentation/ind ex.rst并按照内联说明进行操作。

第3部分-添加您希望记录的内容 (Part 3 - Add the Content You Wish to Document)

• Let’s say you have a python file called my_amazing_class.py that includes a class you wish to document.

  假设您有一个名为my_amazing_class.py的python文件，其中包含您要记录的类。

• In the same folder as the conf.py and index.rst files, create a new file called my_amazing_class.rst and copy-paste-personalize this template:

  在与 conf.py和index.rst文件相同的文件夹中，创建一个名为my_amazing_class.rst的新文件，并将此模板复制粘贴个性化：

This is a template for including classes========================================|.. autoclass:: my_amazing_class.MyAmazingClass|:ref:`Return Home <mastertoc>`

TIP: make sure the folder containing your amazing class is in your PYTHONPATH and that it includes an init file__init__.py

提示：请确保包含惊人类的文件夹位于您的PYTHONPATH ，并且其中包含一个初始化文件__init__.py

• In the index.rst file, edit the Table Of Contents to include the name of the .rst file:

  在index.rst文件中，编辑目录以包括.rst文件的名称：

.. toctree::   :maxdepth: 1   :name: mastertoc

my_amazing_class

第4部分-“编译” (Part 4 - “Compile”)

• In the terminal, inside the documentation folder, run make clean html.

  在终端的documentation文件夹内，运行make clean html 。

• That’s it! You have your first version of your documentation ready to view!

  而已！ 您已经准备好查看文档的第一个版本！

• Open the file documentation/_build/html/index.html in your browser, and see for yourself :)

  在浏览器中打开文件documentation/_build/html/index.html ，亲自看看:)

第5部分-在GitHub Pages上托管 (Part 5 - Host on GitHub Pages)

• Under the root of your project, open a new folder called docs and copy inside it the content of <your_project>/documentation/_build/html/

  在项目的根目录下，打开一个名为docs的新文件夹，并在其中复制<your_project>/documentation/_build / html /的内容。

• Inside this new docs folder, create an empty file called .nojekyll

  在这个新的docs文件夹中，创建一个名为.nojekyll的空文件。

  (This tells GitHub Pages to bypass the default

  (这告诉GitHub Pages绕过默认设置

  Jekyll themes and use the HTML and CSS in your project)

  Jekyll主题，并在您的项目中使用HTML和CSS )

• Push your changes to master branch.

  将您的更改推送到master分支。

• In your repository on GitHub, go to Settings->GitHub Pages->Source

  在GitHub上的存储库中，转到Settings->GitHub Pages->源”

  and s

  和s

  elect master branch/docs folder

  elect master branch/docs文件夹

第6部分-分享！ (Part 6 - Share!)

Yup. That’s it. Wait a couple of minutes for GitHub to update. Share your beautiful documentation site at

对。 而已。 等待几分钟，以便GitHub更新。 在以下位置分享您漂亮的文档站点

https://<your_git_usrname>.github.io/<project_name>/

https://<your_git_usrname>.github.io/<proje proje ct_name> /

TIP: When updating documentation, you need to delete the docs folder and create it again. See more details here.

提示：更新文档时，您需要删除docs文件夹并重新创建。 在这里查看更多详细信息。

结语 (Epilogue)

This is the part where I say something thoughtful about how wonderful it is to create new content in the world. And what a wonderful person you are for choosing to make your original content available, accessible, and easy to use.

在这一部分，我会说一些有关在世界上创建新内容的美妙之处。 您是一个多么出色的人，可以选择使您的原始内容可用，可访问且易于使用。

But hey, you made it all the way here, so you already know this stuff.

但是，嘿，您已经在这里完成了所有工作，因此您已经知道了这些东西。

So if there is something else that you still feel you don’t know, I invite you to explore the documentation website I made for this tutorial. You can watch the talk I gave about Sphinx. Hopefully these will answer some riddles you have left about Sphinx.

因此，如果您仍然不知道其他内容，我邀请您浏览为该教程制作的文档网站 。 您可以观看我发表的有关狮身人面像的演讲 。 希望这些能够回答您留下的关于狮身人面像的困惑。

翻译自: https://www.freecodecamp.org/news/the-riddle-of-sphinx-how-to-document-your-code-easily-bf09a9a1804c/

sphinx