Sagte: Ich möchte, dass Sie Sphinx bequem machen und für alle verwenden
Sphinx ist sehr praktisch, aber der Dokumentationsprozess war sehr umständlich. Deshalb habe ich ein Modul "sphinx-quickstart-plus" erstellt, das Sphinx erweitert.
https://github.com/pashango2/sphinx-qsp
Dies hängt vom Sphinx-Modul ab. Bitte installieren Sie Sphinx im Voraus.
$ pip install sphinx-quickstart-plus
Bisher wurde die Dokumenterstellung als "Sphinx-Schnellstart" eingegeben, aber nur als "Sphinx-Schnellstart-Plus".
$ sphinx-quickstart-plus
Dann wird die folgende Nachricht abgespielt.
Ausgabe
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
...
Die Ausgabe ist genau die gleiche wie beim vorherigen "Sphinx-Schnellstart". Sie könnten denken, "Nichts hat sich geändert", aber bitte bleiben Sie in Kontakt.
Ausgabe
...
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
Schließlich gibt es Fragen, die nicht in "Sphinx-Schnellstart" waren. Die aktuellen Erweiterungen und Beschreibungen lauten wie folgt:
| Erweiterter Name | Erläuterung |
|---|---|
| ext_commonmark | .rstnicht nur.md(CommonMark)Wird verfügbar sein |
| ext_nbshpinx | Jupyter Notebook kann importiert werden |
| ext_blockdiag | Sie können Blockdiagramme zeichnen |
| ext_fontawesome | Font Awesome ist bei reST erhältlich |
| ext_rtd_theme | Sie können das Thema "Dokumente lesen" verwenden |
| ext_autobuild | Sie können Auto Build verwenden |
Diese Sphinx-Erweiterungen sind verfügbar, ohne conf.py zu bearbeiten.
Nicht nur das, wenn Sie sphinx-quickstart-plus erneut starten, ändert sich die Frage am Anfang.
Ausgabe
> Use latest setting? (y/n) [y]: y
Wenn Sie "y" eingeben, beantworten Sie einfach die 5 Elemente "Pfad", "Projektname", "Autor", "Version" und "Freigabe". Ein Dokument mit den gleichen Einstellungen wie das vorherige Dokument wird erstellt. Erinnert sich an die Dokumenteinstellungen, die im vorherigen "Sphinx-Schnellstart-Plus" erstellt wurden.
Übrigens, wenn Sie "n" eingeben, wird die übliche "Sphinx-Schnellstart" -Frage abgespielt. Da die Standardeinstellung jedoch die letzte Einstellung ist, können Sie die Eingabetaste bis auf den geänderten Teil wiederholt drücken, so dass dies einfach ist. ist.
$ 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]: <-Der Standardwert ist die letzte Eingabe
ext_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 schreibt conf.py nicht neu, sondern schreibt Makefile neu.
$ make livehtml
Wenn Sie eingeben, wird die automatische Erstellung gestartet. Für Windows-Benutzer wird "auto_build.bat" generiert. Führen Sie es daher aus.
$ auto_build.bat
Wenn Sie .md wie PyCharm bearbeiten, wird eine temporäre Datei erstellt und auch erstellt. Daher gibt es auch eine Einstellung, mit der das Erstellen einiger temporärer Dateien ignoriert werden kann.
"Sphinx-quickstart-plus" ist lizenzfrei, Sie können es gerne verwenden. Bitte beachten Sie, dass wir nicht für Nachteile verantwortlich sind, die durch die Verwendung dieses Moduls verursacht werden.
https://github.com/pashango2/sphinx-qsp
Da meine Umgebung Ubuntu ist, konnte ich sie auch nicht in Windows- und Mac-Umgebungen testen. Ich denke, es gibt Fehler. Wenn Sie Probleme haben, teilen Sie uns dies bitte im GitHub-Problem- oder Kommentarbereich mit.
Dieses Modul selbst ist ein kleines Modul mit weniger als 400 Zeilen einschließlich Kommentaren. Der Erstellungszeitraum beträgt ungefähr 6 Stunden, und das meiste davon ist Debugging-Arbeit. Es unterstützt jedoch voll und ganz die umfangreichen Argumente und Funktionen von "Sphinx-Schnellstart".
Der Grund, warum Sie dies tun können, ist, dass Sie eine Technologie namens ** Monkey Patch ** verwenden.
Ein Affen-Patch ist ein Patch, der das Verhalten einer vorhandenen Bibliothek missbraucht und dynamisch neu schreibt. Dies ist eine Leistung, die die Eigenschaften dynamischer Sprachen ausnutzt und eine Technik ist, die von kompilierten Sprachen nicht nachgeahmt werden kann. [^ 1]
[^ 1]: Ich habe einen Affen-Patch der Kompilierungssprache unter http://postd.cc/monkey-patching-in-go/ erstellt. Es ist eine ziemlich schwarze Magie mit einem Assembler
</ i> Ergänzung
Affen-Patches schreiben vorhandene Bibliotheksdateien nicht neu.
Es ist eine Methode, um das Verhalten dynamisch zu ändern, ohne die Dateien der vorhandenen Bibliothek zu ändern.
Die Installation von sphinx-quickstart-plus ändert das Verhalten der ursprünglichen Sphinx-Bibliothek überhaupt nicht.
[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)
Der Prozess für sphinx-quickstart ist in einem Modul namens sphinx.quickstart.py geschrieben.
Importieren Sie also normalerweise "sphinx.quickstart", aber die Funktion "ask_user" wird vom Affen-Patch neu geschrieben. Verwenden Sie daher "from .. import ask_user" separat, um den Funktionszeiger der ursprünglichen Verarbeitung nicht zu vergessen. Ich importiere.
from sphinx import quickstart
from sphinx.quickstart import ask_user, generate, do_prompt, nonempty, boolean
Überschreiben Sie die Funktion quickstart.ask_user mit der Funktion monkey_patch_ask_user und entführen Sie sie.
# monkey patch
quickstart.ask_user = monkey_patch_ask_user
Nach einer eigenen Verarbeitung mit der Funktion monkey_patch_ask_user wird die ursprüngliche Funktion quickstart.ask_user aufgerufen.
def monkey_patch_ask_user(d):
...Originalverarbeitung
#Original fragen_Benutzeranruf
ask_user(d)
...Originalverarbeitung
Ich habe verschiedene andere Funktionen mit Affen-Patches entführt, aber im Grunde wird das Gleiche getan.
Rufen Sie abschließend quickstart.main auf.
quickstart.main(argv)
Did you want to further expand ‘sphinx-quickstart-plus’? Editing ‘sphinx-quickstart-plus’ source code for extension is not cool. (Möchten Sie'sphinx-quickstart-plus 'weiter erweitern? Seien Sie nicht dumm, den Code für'sphinx-quickstart-plus' zu bearbeiten, um ihn zu erweitern)
Let’s monkey patch! (Lass uns einen Affenpflaster machen!)
Below is an example of a simple extension. (Der folgende Code ist ein Beispiel für eine einfache Erweiterung.)
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. (Der Code der für die Erweiterung verwendeten Basisklasse lautet wie folgt)
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. (Die Erweiterungsklasse von "Sphinx-Autobuild" lautet wie folgt)
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))
Ich habe persönlich eine Dokumentation erstellt, die aber sehr nützlich ist.