Dit chose: Je veux que vous rendiez Sphinx pratique et que vous l'utilisiez par tout le monde
Sphinx est très pratique, mais le processus de documentation était très lourd. Par conséquent, j'ai fait un module "sphinx-quickstart-plus" qui étend Sphinx.
https://github.com/pashango2/sphinx-qsp
Facile à installer avec pip. Cela dépend du module Sphinx, veuillez donc installer Sphinx à l'avance.
$ pip install sphinx-quickstart-plus
Jusqu'à présent, la création de documents était typée «sphinx-quickstart», mais simplement «sphinx-quickstart-plus».
$ sphinx-quickstart-plus
Ensuite, le message suivant sera lu.
production
Welcome to the Sphinx 1.5.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: document_path
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
...
La sortie est exactement la même que celle du précédent sphinx-quickstart.
Vous pourriez penser: «Rien n’a changé», mais restez en contact.
production
...
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
> ext_commonmark:use CommonMark and AutoStructify (y/n) [n]: y
> ext_nbshpinx:provides a source parser for *.ipynb files (y/n) [n]: y
> ext_blockdiag:Sphinx extension for embedding blockdiag diagrams (y/n) [n]: y
> ext_fontawesome:use font awesome (y/n) [n]: y
> ext_rtd_theme:use Read the Doc theme (y/n) [n]: y
> ext_autobuild:autobuild: Watch a directory and rebuild the documentation (y/n) [n]: y
Enfin, il y a des questions qui n'étaient pas dans sphinx-quickstart.
Les extensions et descriptions actuelles sont les suivantes:
| Nom étendu | La description |
|---|---|
| ext_commonmark | .rstpas seulement.md(CommonMark)Sera disponible |
| ext_nbshpinx | Jupyter Notebook peut être importé |
| ext_blockdiag | Vous pourrez dessiner des schémas fonctionnels |
| ext_fontawesome | Font Awesome sera disponible sur reST |
| ext_rtd_theme | Vous pourrez utiliser le thème Lire la documentation |
| ext_autobuild | Vous pourrez utiliser la construction automatique |
Ces extensions Sphinx seront disponibles sans éditer conf.py.
Non seulement cela, lorsque vous relancez sphinx-quickstart-plus, la question du début change.
production
> Use latest setting? (y/n) [y]: y
Si vous tapez «y», répondez simplement aux 5 éléments «Chemin», «Nom du projet», «Auteur», «Version» et «Version», et un document avec les mêmes paramètres que le document précédent sera créé.
Se souvient des paramètres de document créés dans le précédent sphinx-quickstart-plus.
Au fait, si vous tapez'n ', la question habituelle sphinx-quickstart sera jouée, mais comme le réglage par défaut est le dernier réglage, vous pouvez appuyer sur la touche ʻEnter` à plusieurs reprises sauf pour la partie modifiée, donc c'est facile. est.
$ sphinx-quickstart-plus
> Use latest setting? (y/n) [y]: n
...
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [y]: <-La valeur par défaut est la dernière entrée
conf.py sur chaque sélection d'extensionext_commonmark
conf.py
# ----- CommonMark
source_suffix = [source_suffix, '.md']
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
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)
ext_nbshpinx
conf.py
# ----- Jupyter Notebook nbsphinx
extensions.append('nbsphinx')
exclude_patterns.append('**.ipynb_checkpoints')
ext_blockdiag
conf.py
# ----- blockdiag settings
extensions.extend([
'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag',
'sphinxcontrib.actdiag',
'sphinxcontrib.nwdiag',
'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag',
])
blockdiag_html_image_format = 'SVG'
seqdiag_html_image_format = 'SVG'
actdiag_html_image_format = 'SVG'
nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'
ext_fontawesome
conf.py
# ----- sphinx-fontawesome
import sphinx_fontawesome
extensions.append('sphinx_fontawesome')
ext_rtd_theme
conf.py
# ----- Read the Docs Theme
html_theme = "sphinx_rtd_theme"
ext_autobuild
auto_build ne réécrit pas conf.py, mais réécrit Makefile.
$ make livehtml
Si vous tapez, la construction automatique démarre. Pour les utilisateurs de Windows, ʻauto_build.bat` sera généré, veuillez donc l'exécuter.
$ auto_build.bat
Si vous éditez .md tel que PyCharm, un fichier temporaire sera créé et il sera également construit, il y a donc aussi un paramètre pour ignorer la construction de certains fichiers temporaires.
"Sphinx-quickstart-plus" est sans licence, n'hésitez pas à l'utiliser. Veuillez noter que nous ne sommes pas responsables des inconvénients causés par l'utilisation de ce module.
https://github.com/pashango2/sphinx-qsp
De plus, comme mon environnement est Ubuntu, je n'ai pas pu le tester sur les environnements Windows et Mac. Je pense qu'il y a des bugs. Si vous rencontrez des problèmes, veuillez nous en informer dans la section Problème ou commentaire de GitHub.
Ce module lui-même est un petit module avec moins de 400 lignes, commentaires compris, et la période de création est d'environ 6 heures, et la majeure partie est un travail de débogage.
Cependant, il supporte pleinement les riches arguments et fonctionnalités de sphinx-quickstart.
La raison pour laquelle vous pouvez faire cela est que vous utilisez une technologie appelée ** Monkey Patch **.
Un patch monkey est un patch qui détourne le comportement d'une bibliothèque existante et la réécrit dynamiquement. C'est une prouesse qui tire parti des caractéristiques des langages dynamiques et c'est une technique qui ne peut pas être imitée par les langages compilés. [^ 1]
[^ 1]: J'ai fait un patch monkey du langage de compilation sur http://postd.cc/monkey-patching-in-go/, c'est une jolie magie noire en utilisant un assembleur.
Supplément </ i>
Les patchs Monkey ne réécrivent pas les fichiers de bibliothèque existants.
C'est une méthode pour changer dynamiquement le comportement sans changer les fichiers de la bibliothèque existante.
L'installation de sphinx-quickstart-plus ne change pas du tout le comportement de la bibliothèque d'origine Sphinx.
[Monkey Patch Wikipedia](https://ja.wikipedia.org/wiki/%E3%83%A2%E3%83%B3%E3%82%AD%E3%83%BC%E3%83%91%E3 % 83% 83% E3% 83% 81)
Le processus pour sphinx-quickstart est écrit dans un module appelé sphinx.quickstart.py.
Donc, normalement importez sphinx.quickstart, mais la fonction ʻask_user sera réécrite avec le patch monkey, alors assurez-vous d'utiliser from .. import ask_user` séparément pour ne pas oublier le pointeur de fonction du traitement original. J'importe.
from sphinx import quickstart
from sphinx.quickstart import ask_user, generate, do_prompt, nonempty, boolean
Remplacez la fonction quickstart.ask_user par la fonction monkey_patch_ask_user et détournez-la.
# monkey patch
quickstart.ask_user = monkey_patch_ask_user
Après avoir effectué son propre traitement avec la fonction monkey_patch_ask_user, la fonction d'origine quickstart.ask_user est appelée.
def monkey_patch_ask_user(d):
...Traitement original
#Demande originale_appel utilisateur
ask_user(d)
...Traitement original
J'ai détourné diverses autres fonctions avec des correctifs de singe, mais fondamentalement, la même chose est faite.
Enfin, appelez quickstart.main.
quickstart.main(argv)
Did you want to further expand ‘sphinx-quickstart-plus’? Editing ‘sphinx-quickstart-plus’ source code for extension is not cool. (Souhaitez-vous étendre davantage «sphinx-quickstart-plus»? Ne soyez pas stupide de modifier le code de «sphinx-quickstart-plus» pour l'étendre)
Let’s monkey patch! (Faisons un patch de singe!)
Below is an example of a simple extension. (Le code ci-dessous est un exemple d'extension simple)
from sphinx_qsp import quickstart_plus
# Setting your extension.
your_extension = quickstart_plus.Extension(
"ext_your_ext", "your extensions description.",
conf_py="""
# ----Your Extension
import your_extension_package
extension.append("your-extension_name")
)
""",
package=["your_extension_packge"]
)
# Add your extension.
quickstart_plus.qsp_extensions.extend([
your_extension
])
# Run sphinx-quickstart-plus.
quickstart_plus.main()
The base class of extension is the following code. (Le code de la classe de base utilisée pour l'extension est le suivant)
class Extension(object):
def __init__(self, key, description, conf_py=None, new_makefile=None,
makefile=None, package=None):
self.key = key
self.description = description
self.conf_py = conf_py
self.new_makefile = new_makefile
self.makefile = makefile
self.package = package or []
# noinspection PyUnusedLocal
def extend_conf_py(self, d):
return self.conf_py
def extend_makefile(self, d, make_mode):
return self.new_makefile if make_mode else self.makefile
The extended class of ‘sphinx-autobuild’ is the following code. (La classe d’extension de ‘sphinx-autobuild’ est la suivante)
class AutoBuildExtension(Extension):
def extend_makefile(self, d, make_mode):
if d['batchfile']:
batchfile_path = os.path.join(d['path'], 'auto_build.bat')
source_dir = d['sep'] and 'source' or '.'
build_dir = d['sep'] and 'build' or d['dot'] + 'build'
open(batchfile_path, "w").write(
AUTO_BUILD_BATCH.format(
build_dir=build_dir, source_dir=source_dir,
AUTOBUILD_IGNORE=" ".join(AUTOBUILD_IGNORE),
)
)
makefile = self.new_makefile if make_mode else self.makefile
return makefile.format(" ".join(AUTOBUILD_IGNORE))
J'ai personnellement créé de la documentation, mais c'est vraiment utile.