Docutils configure

docutils 設定資料

Configuration Files

doctuils [1] 可以把設定寫成一個設定檔案，然後讓所有的 Front-End Tools 自動遵循設定檔 的規範，設定檔涵蓋所有內建的預設值，和命列列的選項，有三個預設的設定檔：

1. /etc/docutils.conf: 全系統共用的設定檔。
2. ./docutils.conf: 目前目錄的設定檔，可以想像成專案使用的設定檔。
3. ~/.docutils: 使用者等級的設定檔。

使用順序依序為： 使用者等級 -> 目前目錄等級 -> 全系統。

設定檔語法

首先，預設開啟檔案的編碼為utf-8，為了不要要的困擾建議設定檔使用utf-8編碼。

設定檔由數個 section 組成，每個 section 開始那列都是 [section] ，然後接一連串 "name:value" 的設定值（也可以寫成 name=value）。

每一列開頭為"#"或";"（井號或分號）代表註解，程式會忽略他。

Example:

# These entries affect all processing:
[general]
source-link: yes
datestamp: %Y-%m-%d %H:%M UTC
generator: on
 
# These entries affect HTML output:
[html4css1 writer]
# Required for docutils-update, the website build system:
stylesheet-path: ../docutils/writers/html4css1/html4css1.css
embed-stylesheet: no
field-name-limit: 20

General Setting

footnote_backlinks

允許 footnote 可以連回引用處 (citation)，預設為 Enable.

generator

在文件的註腳加入 "Generated by Docutils" ，預設為 off. Options [2]:--generator, -g, --no-generator .

record_dependencies

輸出 dependen file list 到指定的檔案。 Default: None. Option: --record-dependencies=<file>.

report_level

Verbosity threshold at or above which system messages are reported. Default: warning (2). Options: --report, -r, --verbose, -v, --quiet, -q.

sectnum_xform

Enable or disable the section numbering transform (docutils.transforms.parts.SectNum). Default: enabled (1). Options: --section-numbering, --no-section-numbering.

source_link

Include a "View document source" link in the document footer. URL will be relative to the destination. Default: don't (None). Options: --source-link, -s, --no-source-link.

[1]	reStructuredText front-end tools.

[2]	command line options