# 2. 文件檔案專案¶

## 2.1. 執行sphinx-quickstart指令¶

 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

### 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]: 

### 2.1.2. templates程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. 專案語言¶

 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. 原始檔附檔名¶

 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. 首頁文件名稱設定¶

 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. 檢示程式碼¶

 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. 完成文檔案建置¶

  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¶

 1 make html 

  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)¶

 1 2 3 4 5  'html5_doctype': True, 'html_tag': '', } # Theme options are theme-specific and customize the look and feel of a theme `

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