La documentation est très pratique pour le sphinx. Cependant, sphinx-quickstart n'a besoin que d'un retour, Je me demandais si je pouvais faire quelque chose d'un peu plus. Plus j'utilise le sphinx, plus je ressens cela gênant J'ai fait quelque chose qui s'appelle sphinx-express.
Monologue: C'est une force brute. C'est un script qui n'est ni cool ni beau. Eh bien, c'est comme une étude du module clic, Cela fonctionne comme prévu.
J'utilise Click et PyYAML. De plus, sphinx attend la version 1.7 ou ultérieure.
$ python -m pip install click PyYAML
La première fois qu'il est exécuté avec l'option --setup.
$ 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.
Maintenant sous $ HOME / .sphinx Il copiera les fichiers modèles que possèdent quickstartrc et sphinx.
$ 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
Par défaut, ~ / .sphinx / quickstartrc effectue les opérations suivantes:
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: ======
Après cela, si vous modifiez ce fichier, shpinx-express.py le chargera pour vous Le répertoire du projet sphinx est configuré avec une seule commande.
$ 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.
J'essaye de créer le répertoire du projet sphinx s'il n'existe pas. Le projet utilise par défaut le répertoire du projet. author est le nom d'utilisateur de connexion obtenu avec os.getlogin () par défaut.
$ 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 est En plus de la copie, les corrections simples suivantes sont apportées.
# -- 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 %}
Je ne m'en servirai peut-être pas beaucoup, Si vous définissez des variables dans ~ /, sphinx / quickstartrc, Vous pouvez définir des valeurs pour les variables jinja2 utilisées dans le fichier modèle.
variables:
- NAME=VALUE
TODO Je veux faire un paquet. Non, je devrais le faire ...
Recommended Posts