sphinx 項目根目錄_如何使用Sphinx工具記錄Django項目

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 項目根目錄

本文來自互聯網用戶投稿,該文觀點僅代表作者本人,不代表本站立場。本站僅提供信息存儲空間服務,不擁有所有權,不承擔相關法律責任。
如若轉載,請注明出處:http://www.pswp.cn/news/393811.shtml
繁體地址,請注明出處:http://hk.pswp.cn/news/393811.shtml
英文地址,請注明出處:http://en.pswp.cn/news/393811.shtml

如若內容造成侵權/違法違規/事實不符,請聯系多彩編程網進行投訴反饋email:809451989@qq.com,一經查實,立即刪除!

相關文章

程序員必知之浮點數運算原理詳解

導讀:浮點數運算是一個非常有技術含量的話題,不太容易掌握。許多程序員都不清楚使用操作符比較float/double類型的話到底出現什么問題。 許多人使用float/double進行貨幣計算時經常會犯錯。這篇文章是這一系列中的精華,所有的軟件開發人員都應…

axure選中后橫線切換_3、開關狀態切換 —— Axure實用交互

寫在開頭:開關的制作在幾乎所有原型設計中都會用到,所以美觀自然的交互開關可以給你的原型設計加分不少。本次開關設計主要用到的是邏輯為:選中狀態的切換首先,來看一下演示動畫開始原型設計一、創建元件首先需要打開Axure軟件,并…

Django框架——模型(數據庫操作)

-- models.py-- ORM(object-relation mapping) 實現數據模型與數據庫的解耦;# 對象,關系,映射;1.根 據對象的類型生成表結構;2.將對象、列表的操作,轉換為sql語句;3.將sql查詢到的結果轉換為對象…

leetcode140. 單詞拆分 II(回溯+記憶化)

給定一個非空字符串 s 和一個包含非空單詞列表的字典 wordDict,在字符串中增加空格來構建一個句子,使得句子中所有的單詞都在詞典中。返回所有這些可能的句子。 說明: 分隔時可以重復使用字典中的單詞。 你可以假設字典中沒有重復的單詞。 …

#loj 3058 [HNOI2019] 白兔之舞

單位根反演思博題 模數是亂給的記得整個任意模數ntt k為p-1的約數意味著一定存在k次單位根,設g是p的原根則\(w_{k}^{1}g^{\frac{k-1}{p}}\) 既然k次單位根存在自然考慮單位根反演了 設\(f(i)\)表示跳了i步并且停在了第二維為y的頂點的方案數 設\(st\)表示初始向量而…

標桿徐2018 Linux自動化運維實戰,標桿徐2018 Linux自動化運維系列⑦: SaltStack自動化配置管理實戰...

結合企業自動化集群場景講解,輕松玩轉SaltStack自動化配置管理工具第1章 SaltStack基礎應用SaltStack安裝SaltStack認證Saltstack遠程執行SaltStack配置管理第2章 SaltStack數據系統SaltStack數據系統-Grains 客戶端向服務端發送狀態SaltStack數據系統-paiil 服務…

JS 對象引用問題

var a {n:1}; var b a; a {n:2}; a.x a ;console.log(a.x);console.log(b.x); var a {n:1}; var b a; a.x a {n:2}; console.log(a.x);console.log(b.x); 這兩個問題主要理解兩點就很簡單了。 對象是引用類型,改變賦值只是改變指針的引用。運算符相當于改變…

工程代碼_Egret開發筆記(二)基礎工程代碼閱讀

代碼目錄結構在Egret Wing中打開上一節中我們創建的項目工程,查看代碼目錄結構,Forward在如下圖中標記了各個目錄的及關鍵文件的用途。代碼閱讀理解接下來我們從web入口一步一步閱讀初始代碼。首先打開index.html文件,我們看到index文件內容如…

知曉云助力小程序開發

小程序開發遇到瓶頸雖然騰訊提供了小程序解決方案,https://cloud.tencent.com/solution/la。但是對于普通開發者或者小企業的開發人員來說,購買域名,網站備案、部署SSL證書,安裝會話服務器。業務邏輯上要使用數據庫,緩…

leetcode131. 分割回文串(回溯)

給定一個字符串 s&#xff0c;將 s 分割成一些子串&#xff0c;使每個子串都是回文串。 返回 s 所有可能的分割方案。 示例: 輸入: “aab” 輸出: [ [“aa”,“b”], [“a”,“a”,“b”] ] 代碼 class Solution {List<List<String>> stringListnew ArrayList…

Cracer滲透-windows基礎(系統目錄,服務,端口,注冊表)

系統目錄C:\Windows\system32\config\SAM (保存系統密碼) 無法正常修改&#xff0c;可以進入PE系統進行修改&#xff08;先備份在清空&#xff09;利用結束后&#xff0c;再將之前備份的恢復C:\Windows\System32\drivers\hosts&#xff08;域名解析文件&#xff09;hosts欺騙&a…

java--xml文件讀取(SAX)

SAX解析原理&#xff1a; 使用Handler去逐個分析遇到的每一個節點 SAX方式解析步奏&#xff1a; 創建xml解析需要的handler&#xff08;parser.parse(file,handler)&#xff09; package com.imooc_xml.sax.handler;import java.util.ArrayList;import org.xml.sax.Attributes…

算法訓練營 重編碼_編碼訓練營之后該做什么-以及如何獲得成功

算法訓練營 重編碼by Anthony Morris安東尼莫里斯(Anthony Morris) 編碼訓練營之后該做什么-以及如何獲得成功 (What to do — and how to find success — after a coding bootcamp) It’s almost been two years since I graduated from the Lighthouse Labs Web Developmen…

leetcode860. 檸檬水找零(貪心)

在檸檬水攤上&#xff0c;每一杯檸檬水的售價為 5 美元。 顧客排隊購買你的產品&#xff0c;&#xff08;按賬單 bills 支付的順序&#xff09;一次購買一杯。 每位顧客只買一杯檸檬水&#xff0c;然后向你付 5 美元、10 美元或 20 美元。你必須給每個顧客正確找零&#xff0…

linux防火墻開啟某端口命令行,linux上防火墻 開啟某個端口

linux下防火墻 開啟某個端口直接在/etc/sysconfig/iptables中增加一行&#xff1a;-A RH-Firewall-1-INPUT -m state –state NEW -m tcp -p tcp –dport 8080 -j ACCEPT注意添加位置:-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT-A RH-Fi…

imp命令導入指定表_Sqoop 使用shell命令的各種參數的配置及使用方法

點擊上方藍色字體&#xff0c;選擇“設為星標”回復”資源“獲取更多資源本文作者&#xff1a;Sheep Sun本文鏈接&#xff1a;https://www.cnblogs.com/yangxusun9/p/12558683.html大數據技術與架構點擊右側關注&#xff0c;大數據開發領域最強公眾號&#xff01;暴走大數據點擊…

黑客頻繁來襲 關注云計算的安全與保障

本文講的是 : 黑客頻繁來襲 關注云計算的安全與保障 , 【IT168 資訊】日前&#xff0c;虎嗅網遭受網絡攻擊的事件&#xff0c;引起業內關注。2月27日晚&#xff0c;虎嗅網中斷訪問&#xff0c;虎嗅網新浪官方微博隨即發表聲明&#xff0c;表示網站受到惡意攻擊&#xff0c;隨…

51nod 1100:斜率最大

題目鏈接 斜率最大點對橫坐標必相鄰 #include <bits/stdc.h> using namespace std; const int maxn 1e4 100;struct point {int x, y, pos;bool operator < (const point& rhs)const{return x<rhs.x;} } a[maxn]; double xielv(point a, point b) {return (a…

ik分詞和jieba分詞哪個好_Pubseg:一種單雙字串的BiLSTM中文分詞工具

中文分詞是中文自然語言處理中的重要的步驟&#xff0c;有一個更高精度的中文分詞模型會顯著提升文檔分類、情感預測、社交媒體處理等任務的效果[1]。Pubseg是基于BiLSTM中文分詞工具&#xff0c;基于ICWS2005PKU語料訓練集訓練而成&#xff0c;其優點在于在ICWS2005-PKU語料下…

freecodecamp_freeCodeCamp.org隱私權政策:問題與解答

freecodecampWe take your privacy seriously. And we give you full control over your data.我們把你的隱私當回事。 而且&#xff0c;我們可以完全控制您的數據。 freeCodeCamp doesnt show you ads or sell your data to anyone. Our nonprofit is instead supported by t…