2. 文件檔案專案

2.1. 執行sphinx-quickstart指令

上一個章節我們已經安裝了sphinx,接下來依舊使用命令題示字元來執行sphinx-quickstart指令,建立文件專案. 筆者用命令題示字元在D槽 [1] 建立sphinx教學目錄 [2] ,並切換至sphinx教學目錄 [3] 然後再執行sphinx-quickstart指令 [4] :

1
2
3
4
cd d:
mkdir sphinx教學
cd d:/sphinx教學
sphinx-quickstart

命令題示字元

[1]cd d:
[2]mkdir sphinx教學
[3]cd d:/sphinx教學
[4]sphinx-quickstart
../_images/getting_started_01.jpg

執行sphinx-quickstart指令後,跟著一堆選擇的項目.大部份你只要按Enter使用預設值即可,只有專案名稱(Project name) 和作者名稱是必填的.下面我們就開始一一說明:

2.1.1. 原始與建置目錄是否分離

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Welcome to the Sphinx 1.8.2 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]:

當你直接按Enter如上[n]所示,預設值為否,你可以直接打y按Enter鍵,很明顯一些目錄就在source資料夾內了,我們直接參照下圖即可了解差別.

../_images/getting_started_02.jpg

2.1.2. templates程static目錄前置符號

直接按Enter那前置符號就是底線 _ ,所以就會建立 _templates_static 目錄, 假設你輸入 jeff_ 那就產生 jeff_templatesjeff_static 目錄.

1
2
3
4
Inside 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 [_]:

2.1.3. 專案名稱

  1. 專案名稱-Project name:必填
  2. 作者名稱-Author name(s):必填
  3. 專案釋放版本-Project release:選項,包含軟體版本週期標籤 alpha/beta/rc
1
2
3
4
The project name will occur in several places in the built documentation.
> Project name: sphinx sample
> Author name(s): jeff chou
> Project release []: 1.0.0 rc

2.1.4. 專案語言

預設是en英文的,在這填上 zh_TW

1
2
3
4
5
6
7
If 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]: zh_TW

2.1.5. 原始檔附檔名

原始檔附檔名預設是 .rst,你可以改成 .txt.附檔名只能是 rst或者是txt.

1
2
3
The 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]:

2.1.6. 首頁文件名稱設定

預設首頁文件為index.rst,使用make html之後會產生index.html,這個選項是讓你自訂首頁名稱.

1
2
3
4
5
One 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]:

2.1.7. 插入docstrings模組

1
> autodoc: automatically insert docstrings from modules (y/n) [n]:

2.1.8. 自動測試碼片段

1
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:

2.1.9. 聯結不同專案

1
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:

2.1.10. todo顯示或隱藏

1
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:

2.1.11. 檢查文檔覆蓋率

1
> coverage: checks for documentation coverage (y/n) [n]:

2.1.12. 包含數學-PNG或SVN圖片呈現

1
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:

2.1.13. 包含數學-瀏覽器從MathJax呈現

1
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:

2.1.14. 條件式配置

1
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:

2.1.15. 檢示程式碼

包含聯結python物件源始碼

1
> viewcode: include links to the source code of documented Python objects (y/n) [n]:

2.1.16. github 發怖

git是版本控制軟體.

1
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

2.1.17. 建立Makfile檔案

1
2
3
4
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]:

2.1.18. 建立批次檔

1
> Create Windows command file? (y/n) [y]:

2.1.19. 完成文檔案建置

完成之後建立了下面數個檔案,其中conf.py是主要的設定檔,上面諸多選擇也多在設定檔

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Creating 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 builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

2.1.20. conf設定檔

下面呈現部份程式碼

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'sphinx-doc'
copyright = '2020, jeff chou'
author = 'jeff chou'

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '1.0.0'

2.2. 建立文檔html

執行make批次檔

1
make html

在_bulid資料夾內自動產生html及doctrees目錄及產生文件專案的檔案分別在這兩個資料夾,進入html資料夾內執行index.html, 就可以看到基本文件的樣子::

../_images/getting_started_03.jpg

產生網頁的rst如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
.. sphinx sample documentation master file, created by
   sphinx-quickstart on Tue Nov 27 22:04:07 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sphinx sample's documentation!
=========================================

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

   rst/sample

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

2.3. 設定html 主題(theme)

我們可以從conf.py內的 html_theme 這個設定值設定不同的主題,你可以輕鬆的有不同的風格.

1
2
3
4
5
    'html5_doctype': True,
    'html_tag': '<html>',    
}

# Theme options are theme-specific and customize the look and feel of a theme

下面圖是用sphinxdoc主題設定的結果,記得要再執行make html一次,才能更改文件主題.

../_images/getting_started_04.jpg

下面列出sphinx已經內建的主題:

  • agogo
  • bizstyle
  • classic
  • default
  • epub
  • haiku
  • nature
  • nonav
  • pyramid
  • scrolls
  • sphinxdoc
  • traditional