[PYTHON] Je veux que Sphinx soit pratique et utilisé par tout le monde

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

• Arrêtez car le thème par défaut est difficile à voir --sphinx-quickstart a trop de questions pour s'arrêter à mi-chemin
• Je ne l'utilise pas car il est difficile d'éditer conf.py chaque fois que je crée un document.
• Chaque fois que je vérifie le 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.

Utiliser Markdown

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`.

Composant AutoStructify

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:

• génération en trois arbres --Liens vers d'autres documents --Formule / Formule en ligne [^ 1] --Intégration de reStructuredText

[^ 1]: les extensions telles que sphinx.ext.mathjax doivent être activées pour utiliser des formules

génération toctree

Notation Markdown

* [Title1](doc1.md)
* [Title2](doc2.md)

Liens vers d'autres documents

Notation Markdown

[API Reference](api_ref.md)

Formule / formule en ligne

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

Problème de non-utilisation de la "structure de table" de Commonmark

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
=====  =====  =======
``` ``

Définissez un thème facile à lire

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! !!

Simplifiez la génération de documents

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.

Utilisez la fonction de modèle

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.

Cependant, conf.py n'est pas réécrit!

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())

• Une erreur s'est produite lorsque template_dir est None, nous le corrigerons (05/02/2017)

Il est trop gênant de ne pas pouvoir utiliser le modèle dans conf.py, donc il réécrit la source.

À propos de la réécriture de la source de Sphinx (PostScript 08/02/2017)

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é.

Rendre Sphinx-Quickstart pratique

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.

2017-03-06 PostScript

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.

Faites une compilation automatique avec sphinx-autobuild

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

• Veuillez noter qu'une erreur se produira à moins que l'indentation ne soit définie sur TAB en tant que spécification Makefile.

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

Importer le bloc-notes Jupyter (Ajouté le 06/02/2017)

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.

</ i> Utiliser Font Awesome (Ajouté le 11/02/2017)

pip install sphinx_fontawesome

import sphinx_fontawesome
extensions = ['sphinx_fontawesome']

<i class="fa fa-exclamation-triangle" aria-hidden="true"></i>