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