sphinx-quickstart变得混乱，我尝试创建替代命令，压力消失了


介绍

sphinx对于文档创建非常方便。
但是，sphinx-quickstart基本上只需要返回，但是
我想知道我是否还能做更多的事情。
我使用狮身人面像的次数越多，我感到越发麻烦，
我做了一个叫狮身人面像的东西。

自言自语：这是一种蛮力。这个脚本既不酷也不美观。
我正在使用typer模块进行选项解析，因此它可以在Python 3.6及更高版本中按预期工作。

相关模块

请从github克隆并安装。

1
2
3
$ git clone https://github.com/iisaka51/sphinx-express.git
$ cd sphinx-express
$ python setup.py install

如何使用

第一次，使用--setup选项执行。

1
2
3
4
5
6
7
8
$ sphinx-express.py --setup

You should install follows packages.
python -m pip install sphinx-rtd-theme sphinx-charts pallets_sphinx_themes sphinxcontrib-runcmd sphinxcontrib-napoleon

your configfile: /Users/goichiiisaka/.sphinx/quickstartrc
your templatedir: /Users/goichiiisaka/.sphinx/templates/quickstart
quickstart templates of sphinx into your templatedir.

现在在$ HOME / .sphinx下
它将复制quickstartrc和sphinx具有的模板文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
$ tree  ~/.sphinx/
/Users/goichiiisaka/.sphinx/
├── quickstartrc
└── templates
    └── quickstart
        ├── Makefile.new_t
        ├── Makefile_t
        ├── conf.py_t
        ├── make.bat.new_t
        ├── make.bat_t
        └── master_doc.rst_t

2 directories, 7 files

?/ .sphinx / quickstartrc默认为：

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
31
32
33
34
35
36
37
sep: true
language: ja
suffix: .rst
master: index
makefile: true
batchfile: true
autodoc: true
doctest: false
intersphinx: false
todo: false
coverage: false
imgmath: true
mathjax: true
ifconfig: true
viewcode: true
project: sample
version: 0.0.1
release: 0.0.1
lang: ja
make_mode: true
ext_mathjax: true
extensions:
- pallets_sphinx_themes
- sphinx_rtd_theme
- sphinx.ext.autodoc
- sphinx.ext.mathjax
- sphinx.ext.autosectionlabel
- sphinxcontrib.blockdiag
- sphinxcontrib.seqdiag
- sphinxcontrib.blockdiag
- sphinxcontrib.nwdiag
- sphinxcontrib.rackdiag
- sphinxcontrib.httpdomain
- sphinxcontrib.runcmd
- recommonmark
mastertocmaxdepth: 2
project_underline: ======

  • sep：在单独的目录或布尔中管理源和生成的文档
  • 点的前缀的定义：模板等()
  • 项目：项目名称
  • 作者：作者
  • 版本：版本号
  • 发布：发布编号
  • 语言：文档中使用的语言
  • 后缀：源后缀
  • 主文件：主文件名称
  • 扩展：使用扩展
  • makefile：makefile类型为bool
  • batchfile：生成make.bat或bool

之后，如果您修改此文件，
shpinx-express.py将为您加载它，因此
单个命令将设置sphinx项目目录。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ sphinx-express sample
Welcome to the Sphinx 3.2.1 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: sample

Creating file /Users/goichiiisaka/docs/sample/source/conf.py.
Creating file /Users/goichiiisaka/docs/sample/source/index.rst.
Creating file /Users/goichiiisaka/docs/sample/Makefile.
Creating file /Users/goichiiisaka/docs/sample/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/goichiiisaka/docs/sample/source/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.

如果狮身人面像项目目录不存在，则创建该目录。
该项目默认为项目目录。
author是os.getlogin()默认获得的登录用户名。

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
$ sphinx-express --help
Usage: sphinx-express [OPTIONS] PROJECT_DIR

  Create required files for a Sphinx project.

Arguments:
  PROJECT_DIR  [required]

Options:
  -p, --project PROJECT_NAME      project name.  default is basename of
                                  PROJECT_DIR.

  -a, --author AUTHOR_NAME        author name. default is "goichiiisaka"
                                  [default: goichiiisaka]

  -v, --ver VERSION               version of project.  [default: 0.0.1]
  -l, --lang LANG                 document language.  [default: ja]
  -t, --templatedir TEMPLATE_DIR  template directory for template files.
                                  [default: /Users/goichiiisaka/.sphinx/templa
                                  tes/quickstart]

  -d, --define NAE=VALUE          define a template variable.
  -c, --configfile CONFIG_FILEPATH
                                  sphinx-express configfile.  [default:
                                  /Users/goichiiisaka/.sphinx/quickstartrc]

  -N, --new                       Ignore least configures.  [default: False]
  --setup                         Copy templates and exit.  [default: False]
  --version                       Show version and exit.  [default: False]
  --help                          Show this message and exit.

模板

?/ .sphinx /模板/ quickstart / conf.py_t是
不仅复印，而且还进行以下清醒的更正。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#

# Avilable Themes: alabaster
{% set default_theme="alabaster" %}
{%- if 'sphinx_rtd_theme' in extensions -%}
# sphinx_rtd_theme
{% set default_theme="sphinx_rtd_theme" %}
{%- endif -%}
{%- if 'pallets_sphinx_themes' in extensions -%}
# babel, click, flask, jinja, platter, pocoo, werkzeug
{% set default_theme="flask" %}
{%- endif -%}
#
html_theme = "{{ default_theme }}"
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{%- if 'sphinxcontrib.seqdiag' in extensions %}
# -- Options for seqdiag output -------------------------------------------

# curl -O https://ja.osdn.net/projects/ipafonts/downloads/51868/IPAfont00303.zip
import os
basedir = os.path.abspath(os.path.dirname(__file__))
seqdiag_fontpath = basedir + '/_fonts/IPAfont00303/ipagp.ttf'
seqdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.nwdiag' in extensions %}
# -- Options for nwdiag output --------------------------------------------

nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.blockdiag' in extensions %}
# -- Options for blockdiag output ------------------------------------------

blockdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.actdiag' in extensions %}
# -- Options for actdiag output --------------------------------------------

actdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.httpdomain' in extensions %}
# -- Options for httpdomain output ------------------------------------------

# List of HTTP header prefixes which should be ignored in strict mode:
http_headers_ignore_prefixes = ['X-']

# Strips the leading segments from the endpoint paths
# by given list of prefixes:
# http_index_ignore_prefixes = ['/internal', '/_proxy']

# Short name of the index which will appear on every page:
# http_index_shortname = 'api'

# Full index name which is used on index page:
# http_index_localname = "My Project HTTP API"

# When True (default) emits build errors when status codes,
# methods and headers are looks non-standard:
http_strict_mode = True
{%- endif %}


{%- if 'recommonmark' in extensions %}
# -- Options for recommonmark output ----------------------------------------
import recommonmark
from recommonmark.transform import AutoStructify

# At the bottom of conf.py
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)
{%- endif %}

提示

我可能不会使用太多，但是
如果您在?/，sphinx / quickstartrc，中定义变量
您可以将值设置为模板文件中使用的jinja2变量。

1
2
variables:
- NAME=VALUE