Die Dokumentation ist für Sphinx sehr praktisch. Sphinx-Schnellstart benötigt jedoch grundsätzlich nur eine Rückkehr, Ich fragte mich, ob ich etwas mehr tun könnte. Je öfter ich Sphinx benutze, desto störender fühle ich mich Ich habe etwas namens [Sphinx-Express] gemacht (https://github.com/iisaka51/sphinx-express).
Monolog: Es ist eine rohe Kraft. Es ist ein Skript, das weder cool noch schön ist. Nun, es ist wie eine Studie des Klickmoduls. Es funktioniert wie erwartet.
Ich benutze Click und PyYAML. Außerdem erwartet Sphinx Version 1.7 oder höher.
$ python -m pip install click PyYAML
Das erste Mal wird es mit der Option --setup ausgeführt.
$ 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.
Jetzt unter $ HOME / .sphinx Es werden die Vorlagendateien kopiert, über die quickstartrc und sphinx verfügen.
$ 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
Standardmäßig führt ~ / .sphinx / quickstartrc Folgendes aus:
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: ======
Wenn Sie danach diese Datei ändern, shpinx-express.py lädt es für Sie Das Sphinx-Projektverzeichnis wird mit einem einzigen Befehl eingerichtet.
$ sphinx-express.py 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.
Ich versuche das Sphinx-Projektverzeichnis zu erstellen, wenn es nicht existiert. Das Projekt verwendet standardmäßig das Projektverzeichnis. Autor ist der Login-Benutzername, der standardmäßig mit os.getlogin () abgerufen wird.
$ python sphinx-express.py --help
()
Usage: sphinx-express.py [OPTIONS] [PROJECT_DIR]
Create required files for a Sphinx project.
Options:
-p, --project TEXT project name. default is basename of PROJECT_DIR.
-a, --author TEXT author name. default is "goichiiisaka"
-v, --ver TEXT version of project. default is '0.0.1'
-l, --lang TEXT document language. default is 'ja'
-t, --templatedir PATH template directory for template files. default:
/Users/goichiiisaka/.sphinx/templates/quickstart
-d, --define_value TEXT define a template variable. NAME=VALUE
-c, --configfile PATH sphinx-express configfile. default:
/Users/goichiiisaka/.sphinx/quickstartrc
-N, --new Ignore least configures.
--setup Copy quickstart templates and exit.
--version Show the version and exit.
--help Show this message and exit.
~ / .sphinx / templates / quickstart / conf.py_t ist Zusätzlich zum Kopieren werden die folgenden einfachen Korrekturen vorgenommen.
# -- 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 }}"
{%- 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 %}
Ich kann es nicht viel benutzen, Wenn Sie Variablen in ~ /, sphinx / quickstartrc definieren, Sie können Werte für die in der Vorlagendatei verwendeten jinja2-Variablen festlegen.
variables:
- NAME=VALUE
TODO Ich möchte ein Paket machen. Nein, ich sollte es tun ...
Recommended Posts