Sphinx est un très bel outil de génération de documents. J'ai essayé de rendre cet excellent outil populaire en interne, mais personne ne l'utilise.
J'ai repensé au moment où tout le monde abandonnerait Sphinx.
--Je ne sais pas ou je veux me souvenir de reStructuredText
conf.py
chaque fois que je crée un document.make html
est gênant, donc je ne vais pas l'utiliser
――Récemment, j'écris des documents avec Jupyter, alors ...Est-ce un tel endroit? C'est peut-être la raison principale pour laquelle Sphinx n'est pas si populaire.
Malheureusement, le langage de balisage courant est «Markdown» au lieu de «reStructuredText». Je pense que tout le monde peut utiliser Markdown
.
Sphinx pourra utiliser Markdown
avec recommonmark
.
Beaucoup de gens ont écrit des articles sur la façon de définir recommonmark
, veuillez vous référer aux articles suivants.
J'ai essayé Sphinx avec Markdown (Partie 2)
recommonmark
peut être installé avec pip.
pip install commonmark recommonmark
Modifiez conf.py
comme suit.
conf.py
source_suffix = ['.rst', '.md']
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
Il décrit également le composant ʻAutoStructify qui étend le
recommonmark`.
Après avoir configuré le composant ʻAutoStructify, vous pouvez utiliser diverses extensions de
reStructuredText à partir du markdown. ʻEdit
conf.py pour activer le composant AutoStructify
.
conf.py
from recommonmark.transform import AutoStructify
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
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)
Lors de la démarque, vous pourrez:
reStructuredText
[^ 1]: les extensions telles que sphinx.ext.mathjax
doivent être activées pour utiliser des formules
Notation Markdown
* [Title1](doc1.md)
* [Title2](doc2.md)
Notation Markdown
[API Reference](api_ref.md)
Notation Markdown
```math
E = m c^2
``` ``
Vous pouvez également utiliser des formules en ligne.
Notation Markdown
This formula `$ y=\sum_{i=1}^n g(x_i) $`
référence http://recommonmark.readthedocs.io/en/latest/auto_structify.html
C'est bien de pouvoir écrire des démarques avec recommonmark
, mais je ne peux pas utiliser de tableaux.
C'est parce que CommonMark
ne prend pas en charge les tables, et il semble peu probable que les tables soient supportées dans un proche avenir.
Le problème a également été soulevé sur le GitHub de recommonmark
, mais il indique" Dois-je utiliser ʻeval_rst`? "
https://github.com/rtfd/recommonmark/issues/3
Quand il s'agit de composition de table, reStructuredText
est plus expressif, et ʻeval_rst` ne rompt pas la description de démarque, donc je pense que c'est bien pour le moment.
Dans ʻeval_rst`, la structure de la table est la suivante.
```eval_rst
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
``` ``
Pour le moment, Markdown
et ses extensions sont maintenant disponibles, donc c'est devenu assez pratique.
Le reste est un paramètre de thème facile à lire.
J'ai essayé plusieurs thèmes, mais je pense que le Read The Docs Theme est le plus facile à lire.
Vous pouvez facilement le faire avec le pip d'installation.
pip install sphinx_rtd_theme
Puis éditez conf.py
.
conf.py
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
C'est beaucoup plus facile à voir! !!
Le thème est devenu plus facile à voir et il est devenu assez pratique.
Au fait, j'ai défini Markdown
, défini le thème et modifié une bonne quantité de conf.py
.
Ce travail ** doit être fait à chaque fois que je crée un document **, c'est trop gênant, qu'est-ce que c'est?
Comme prévu, éditer conf.py
à chaque fois est trop pénible, utilisons la fonction template.
** Mise en garde ** Actuellement, pour utiliser le modèle conf.py, éditez le fichier source de la version Sphinx (1.5.2). Si vous le faites, veuillez le faire à vos propres risques.
sphinx-quickstart
a une option appelée --templatedir
.
sphinx-quickstart
utilise jinja2
pour générer divers fichiers tels que conf.py
et Makefile
à partir du modèle.
Tout ce que vous avez à faire est de préparer un fichier modèle qui utilise le conf.py
avec lequel vous vous êtes trompé comme modèle!
Le modèle de fichier modèle doit se trouver à l'emplacement suivant, veuillez le lire comme il convient pour chaque environnement.
Chemin Python / site-packages / Sphinx-x.x.x-pyx.x.egg / sphinx / templates / quickstart
Si vous ne trouvez pas le fichier, recherchez le fichier conf.py_t
pour le trouver.
Mettez conf.py_t
avec recommonmark
et rtd_theme
sur l'essentiel.
https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e
Placez conf.py_t
quelque part dans un répertoire approprié.
Il y a quelques fichiers dans le répertoire des modèles, mais pour autant que je lis la source de sphinx-quickstart
, le fichier modèle inexistant semble regarder le fichier modèle système, il n'est donc pas nécessaire de copier tous les fichiers.
Nom du fichier de modèle | La description |
---|---|
conf.py_t | conf.modèle py |
Makefile.new_t | Modèle Makefile version simple |
Makefinle_t | Modèle Makefile |
make.bat.new_t | Faire une version simple.modèle de chauve-souris |
make.bat_t | make.modèle de chauve-souris |
master_doc.rst_t | Première génération.premier modèle |
Exécutez sphinx-quickstart
avec le répertoire contenant le fichier modèle.
sphinx-quickstart --templatedir=my_sphinx_template
Cependant, conf.py
n'est pas réécrit quel que soit le nombre d'exécutions de la commande.
D'autres fichiers tels que Makefile
sont réécrits, mais conf.py
n'est pas réécrit, alors lisez la source.
Le code est le suivant à la ligne 442 de sphinx / quickstart.py
.
quickstart.py
with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
conf_text = convert_python_source(f.read())
Seul conf.py_t
spécifie directement les fichiers sous le package.
quickstart.py
# with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
if not conf_path or not path.isfile(conf_path):
conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')
with open(conf_path) as f:
conf_text = convert_python_source(f.read())
Il est trop gênant de ne pas pouvoir utiliser le modèle dans conf.py
, donc il réécrit la source.
Actuellement, c'est un bogue que la fonction de modèle ne fonctionne pas pour conf.py
.
Les changements ci-dessus ont été retirés et fusionnés et seront corrigés dans la version 1.5.3, qui sera publiée à la mi-mars. J'ai fait une pull request sur Github pour la première fois, mais j'ai fait beaucoup d'erreurs, et je tiens à remercier les contributeurs de Sphinx qui m'ont accompagné.
Le modèle est un peu bâclé, mais il devient de plus en plus pratique au fur et à mesure que je suis libéré de l'édition de conf.py
à chaque fois.
sphinx-quickstart
est un problème qui n'est plus rapide car le nombre d'éléments augmente avec chaque version.
Puisque sphinx-quickstart
a différentes options, vous pouvez créer un fichier batch qui applique toutes les options, mais c'est très gênant car il y a beaucoup d'options.
Je vais donc écrire un script Python qui rend le démarrage rapide rapide.
my-sphinx-quickstart.py
#! codig:utf-8
import sys
from sphinx.quickstart import ask_user, generate, DEFAULT_VALUE
d = DEFAULT_VALUE.copy()
d["path"] = sys.argv[1]
d["project"] = sys.argv[2]
d["author"] = sys.argv[3]
#Réglage fixe
d["version"] = "1.0"
d["language"] = "ja"
#Makefile simple
d["make_mode"] = True
#Paramètres d'extension
d["ext_mathjax"] = True
template_dir = "Chemin du modèle ou Aucun"
#Questions s'il y a des paramètres manquants (non requis, si vous le souhaitez)
ask_user(d)
#Génération de documents
generate(d, templatedir=template_dir)
Veuillez réécrire le contenu par vous-même. Dans l'exemple ci-dessus, si vous exécutez avec le chemin du projet, le nom du projet et le nom de l'auteur comme arguments, tout le reste créera un document avec les paramètres par défaut.
Fondamentalement, le document est créé en passant le dictionnaire de paramètres et le répertoire de modèles à la méthode sphinx.quickstart.generate
.
Il peut être pratique de déplacer les paramètres vers un fichier externe avec Json ou d'écrire un script à définir avec l'interface graphique.
En partageant ce répertoire de scripts et de modèles en interne, vous pouvez créer instantanément une génération de documents personnalisés. Cela doit être pratique.
J'ai écrit j'ai fait "sphinx-quickstart-plus" pour rendre la documentation Sphinx pratique, le réglage de conf.py dans cet article est Il s'agit d'un outil généré automatiquement.
Cela vous libère des tracas liés à l'édition de «sphinx-quickstart» et de «conf.py» lors de la création de votre documentation. À ce stade, je pense que c'est assez pratique.
Chaque fois que je mets à jour et vérifie la documentation, je dois taper make html
, mais si j'utilise sphinx-autobuild
, il sera construit automatiquement.
Il peut être installé avec pip.
pip install sphinx-autobuild
Après l'installation, la surveillance des fichiers démarrera avec la commande suivante, et elle sera construite en même temps que la mise à jour.
sphinx-autobuild <Répertoire source> <Créer un répertoire de sortie d'artefact>
Cette commande est longue et lourde à taper à chaque fois, il est donc utile d'ajouter le code suivant au Makefile
généré.
Pour Makefile
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
Pour le nouveau Makefile
livehtml:
sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html
La commande suivante lancera la surveillance automatique de la construction.
make livehtml
Accédez au document avec localhost: 8000
.
En passant, il est pratique d'ajouter le code respectif à Makefile_t
et Makefile.new_t
avec la fonction de modèle mentionnée précédemment.
Mettez les modèles Makefile_t
et Makefile.new_t
sur l'essentiel.
https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e
Récemment, je pense que le nombre de personnes qui écrivent des documents avec Jupyter a augmenté. Il existe une extension de Sphinx appelée nbsphinx qui vous permet de capturer des notebooks Jupyter.
L'installation est facile avec pip
.
pip install nbsphinx
Modifiez conf.py
comme d'habitude.
conf.py
extensions = [
'nbsphinx',
'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']
Assurez-vous que l'extension nbsphinx
et le modèle d'ignorer contiennent **. Ipynb_checkpoints
.
Ajoutez ensuite le cahier à toctree
, écrivez le nom du fichier sans l'extension .ipynb
.
Veuillez noter que si vous ne mettez pas le titre (# title
) sur la première ligne du carnet, il ne sera pas reconnu.
Dans l'exemple ci-dessous, un fichier appelé jupyter.ipynb
est ajouté en tant que document.
Welcome to test's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
jupyter
Le notebook Jupyter a été ajouté!
Il peut également être utile d'ajouter nbsphinx
au modèle conf.py_t
.
Font Awesome améliore l'expressivité des documents avec diverses icônes de polices. Qiita prend également en charge Font Awesome.
Pour utiliser Font Awesome avec Sphinx, utilisez sphinx_fontawesome, l'installation est facile avec pip
comme d'habitude.
pip install sphinx_fontawesome
Modifiez conf.py
.
import sphinx_fontawesome
extensions = ['sphinx_fontawesome']
Si vous souhaitez l'utiliser à partir du démarque, tapez HTML normalement.
<i class="fa fa-exclamation-triangle" aria-hidden="true"></i>
Vous pouvez utiliser Font Awesome depuis le markdown Sphinx comme ceci.
Veuillez vous référer au Readme de sphinx_fontawesome pour savoir comment utiliser à partir de reStructuredText
.
Pour ceux qui veulent travailler dur avec reStructuredText
, il existe un plugin dans Atom pour prévisualiser reStructuredText
.
rst-preview: https://atom.io/packages/rst-preview
Vous pouvez voir l'aperçu avec ctrl-shift-r
, qui utilise pandoc
, donc veuillez d'abord l'installer.
Sphinx présente quelques inconvénients dans de nombreux endroits, mais une fois l'environnement en place, cela peut être assez pratique.
Markdown
―― En cas d'urgence, vous pouvez également écrire reStructuredText
ensemble.Je pense que nous nous rapprochons de l'environnement documentaire le plus solide.
~~ Enfin, réécrivez conf.py
avec la fonction template à vos risques et périls, ou attendez la version 1.5.3 de Sphinx. ~~
Le modèle a été corrigé dans la dernière version de Sphinx 1.5.3.
J'ai écrit j'ai fait "sphinx-quickstart-plus" pour rendre la documentation Sphinx pratique, le réglage de conf.py dans cet article est Il s'agit d'un outil généré automatiquement.
Recommended Posts