.. meta::
   :http-equiv=Content-Type: text/html; charset=utf-8
 
**********************
文件檔案專案
**********************  
   
執行sphinx-quickstart指令
======================================

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

.. code-block:: bat
  :linenos:
  
  cd d:
  mkdir sphinx教學
  cd d:/sphinx教學
  sphinx-quickstart 
  
.. rubric:: 命令題示字元
  
.. [#f1] cd d:
.. [#f2] mkdir sphinx教學
.. [#f3] cd d:/sphinx教學
.. [#f4] sphinx-quickstart
  
.. image:: ../img/getting_started_01.jpg
   :scale: 30%

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

.. _我的參考標籤:

原始與建置目錄是否分離
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bat
  :linenos:
 
  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資料夾內了,我們直接參照下圖即可了解差別.

.. image:: ../img/getting_started_02.jpg
   :scale: 50%

templates程static目錄前置符號
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

直接按Enter那前置符號就是底線 **_** ,所以就會建立 **_templates** 和 **_static** 目錄,
假設你輸入 **jeff_** 那就產生 **jeff_templates** 和 **jeff_static** 目錄.

.. code-block:: bat
  :linenos:
  
  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 [_]: 
  
專案名稱
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. 專案名稱-Project name:必填
#. 作者名稱-Author name(s):必填
#. 專案釋放版本-Project release:選項,包含軟體版本週期標籤 alpha/beta/rc

.. code-block:: bat
  :linenos:
    
  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
  
專案語言
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: c
  :linenos:
    
  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

原始檔附檔名
~~~~~~~~~~~~~~~~~~~~~~~~~~~

原始檔附檔名預設是 .rst,你可以改成 .txt.附檔名只能是 rst或者是txt.
 
.. code-block:: bat
  :linenos: 
  
  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]:

首頁文件名稱設定
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bat
  :linenos:
  
  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]:

插入docstrings模組
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
.. code-block:: bat
  :linenos:
 
  > autodoc: automatically insert docstrings from modules (y/n) [n]:

自動測試碼片段
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bat
  :linenos:
  
  > doctest: automatically test code snippets in doctest blocks (y/n) [n]:

聯結不同專案
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
    
  > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: 

todo顯示或隱藏
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
    
  > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:

檢查文檔覆蓋率
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
    
  > coverage: checks for documentation coverage (y/n) [n]:

包含數學-PNG或SVN圖片呈現
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:  
  
  > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:

包含數學-瀏覽器從MathJax呈現
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
  
  > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:

條件式配置
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
    
  > ifconfig: conditional inclusion of content based on config values (y/n) [n]:

檢示程式碼
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

包含聯結python物件源始碼
  
.. code-block:: bat
  :linenos:  
  
  > viewcode: include links to the source code of documented Python objects (y/n) [n]:
  
github 發怖
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

git是版本控制軟體.

.. code-block:: bat
  :linenos:
    
  > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

建立Makfile檔案
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bat
  :linenos:
    
  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]:

建立批次檔
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
.. code-block:: bat
  :linenos:
    
  > Create Windows command file? (y/n) [y]:

完成文檔案建置
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bat
  :linenos:
  
  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.
 
conf設定檔
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

下面呈現部份程式碼

.. literalinclude:: ../conf.py
   :language: python
   :linenos:
   :lines: 1-30
 
建立文檔html
======================================  

執行make批次檔

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

.. image:: ../img/getting_started_03.jpg
   :scale: 50%

產生網頁的rst如下:
   
.. literalinclude:: ../tmp/index.rst
   :language: rst
   :linenos:
   
設定html 主題(theme)
====================================== 

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

.. literalinclude:: ../conf.py
   :language: python
   :linenos:
   :lines: 83-87   
   
下面圖是用sphinxdoc主題設定的結果,記得要再執行make html一次,才能更改文件主題.

.. image:: ../img/getting_started_04.jpg
   :scale: 50%
   
下面列出sphinx已經內建的主題:

.. hlist::
    :columns: 6
      
    * agogo
    * bizstyle  
    * classic
    * default
    * epub
    * haiku  
    * nature
    * nonav
    * pyramid
    * scrolls
    * sphinxdoc
    * traditional