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:
現在,有兩種方法可以繼續:
You can use sphinx-apidoc to generate completely automatic documentation, or
您可以使用sphinx-apidoc 生成全自動文檔,或者
- 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 項目根目錄