[PYTHON] Ich möchte, dass Sphinx bequem ist und von allen benutzt wird

Sphinx ist ein sehr schönes Tool zur Dokumentenerstellung. Ich habe versucht, dieses großartige Tool intern populär zu machen, aber niemand benutzt es.

Ich schaute zurück, als jeder die Sphinx aufgeben würde.

Ist es so ein Ort? Vielleicht ist dies der Hauptgrund, warum Sphinx nicht so beliebt ist.

Markdown verwenden

Leider ist die Mainstream-Markup-Sprache "Markdown" anstelle von "reStructuredText". Ich denke, jeder kann "Markdown" verwenden.

Sphinx kann "Markdown" mit "Recononmark" verwenden. Viele Leute haben Artikel darüber geschrieben, wie man "Empfehlungszeichen" setzt. Bitte lesen Sie die folgenden Artikel.

Ich habe Sphinx mit Markdown ausprobiert (Teil 2)

reconmark kann mit pip installiert werden.

pip install commonmark recommonmark

Bearbeiten Sie conf.py wie folgt.

conf.py


source_suffix = ['.rst', '.md']

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

Es beschreibt auch die Komponente "AutoStructify", die die "Recommonmark" erweitert.

AutoStructify-Komponente

Wenn Sie die Komponente "AutoStructify" einrichten, können Sie verschiedene Erweiterungen von "reStructuredText" aus dem Markdown verwenden. Bearbeiten Sie "conf.py", um die "AutoStructify" -Komponente zu aktivieren.

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)

Auf dem Abschlag können Sie:

--Zuchtbaumgenerierung

[^ 1]: Erweiterungen wie "sphinx.ext.mathjax" müssen aktiviert sein, um Formeln verwenden zu können

toctree Generation

Markdown-Notation


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

Links zu anderen Dokumenten

Markdown-Notation


[API Reference](api_ref.md)

Formel / Inline-Formel

Markdown-Notation


```math
E = m c^2
``` ``

Sie können auch Inline-Formeln verwenden.

Markdown-Notation


This formula `$ y=\sum_{i=1}^n g(x_i) $`

Referenz http://recommonmark.readthedocs.io/en/latest/auto_structify.html

Problem, dass die "Tabellenstruktur" von Commonmark nicht verwendet werden kann

Es ist schön, Markdowns mit "Recommonmark" schreiben zu können, aber ich kann keine Tabellen verwenden. Dies liegt daran, dass "CommonMark" keine Tabellen unterstützt und es unwahrscheinlich ist, dass Tabellen in naher Zukunft unterstützt werden.

Das Problem wurde auch auf dem GitHub von "Recommonmark" angesprochen, aber es heißt "Soll ich" eval_rst "verwenden?"

https://github.com/rtfd/recommonmark/issues/3

Wenn es um die Tabellenkomposition geht, ist "reStructuredText" ausdrucksvoller, und "eval_rst" bricht die Markdown-Beschreibung nicht, daher denke ich, dass dies vorerst in Ordnung ist.

Die Tabellenstruktur ist wie folgt mit eval_rst.

```eval_rst
=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
``` ``

Stellen Sie ein einfach zu lesendes Thema ein

Derzeit sind "Markdown" und seine Erweiterungen verfügbar, sodass es recht praktisch geworden ist. Der Rest ist eine einfach zu lesende Themeneinstellung.

Ich habe mehrere Themen ausprobiert, aber ich denke, das Read The Docs Theme ist am einfachsten zu lesen.

Sie können dies problemlos mit dem Installationsrohr tun.

pip install sphinx_rtd_theme

Dann bearbeiten Sie conf.py.

conf.py


import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Es ist viel einfacher zu sehen! !!

rtd.png

Vereinfachen Sie die Dokumentenerstellung

Das Thema ist leichter zu sehen und sehr praktisch geworden.

Übrigens habe ich "Markdown" eingestellt, das Thema festgelegt und eine ganze Menge "conf.py" bearbeitet. Diese Arbeit ** muss jedes Mal ausgeführt werden, wenn ich ein Dokument erstelle **, es ist zu unpraktisch, was ist das?

Wie erwartet ist es zu schmerzhaft, conf.py jedes Mal zu bearbeiten. Verwenden wir die Vorlagenfunktion.

** Hinweis ** Um die conf.py-Vorlage zu verwenden, bearbeiten Sie derzeit die Quelldatei der Sphinx-Version (1.5.2). Wenn Sie dies tun, tun Sie dies bitte auf eigenes Risiko.

Verwenden Sie die Vorlagenfunktion

sphinx-quickstart hat eine Option namens --templatedir. sphinx-quickstart verwendet jinja2, um verschiedene Dateien wie conf.py und Makefile aus der Vorlage zu generieren.

Alles was Sie tun müssen, ist eine Vorlagendatei vorzubereiten, die die "conf.py" verwendet, die Sie als Vorlage durcheinander gebracht haben!

Die Vorlage für die Vorlagendatei sollte sich am folgenden Speicherort befinden. Bitte lesen Sie sie für jede Umgebung entsprechend.

Python-Pfad / Site-Pakete / Sphinx-x.x.x-pyx.x.egg / sphinx / templates / quickstart

Wenn Sie die Datei nicht finden können, suchen Sie nach der Datei "conf.py_t", um sie zu finden. Setzen Sie "conf.py_t" mit "Recommonmark" und "rtd_theme" auf das Wesentliche.

https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e

Platzieren Sie conf.py_t irgendwo in einem geeigneten Verzeichnis. Es gibt einige Dateien im Vorlagenverzeichnis, aber soweit ich die Quelle von "sphinx-quickstart" lese, scheint die nicht vorhandene Vorlagendatei die Systemvorlagendatei zu betrachten, so dass nicht alle Dateien kopiert werden müssen.

Name der Vorlagendatei Erläuterung
conf.py_t conf.py Vorlage
Makefile.new_t Einfache Version Makefile-Vorlage
Makefinle_t Makefile-Vorlage
make.bat.new_t Einfache Version machen.Fledermaus Vorlage
make.bat_t make.Fledermaus Vorlage
master_doc.rst_t Zuerst generiert.erste Vorlage

Conf.py wird jedoch nicht umgeschrieben!

Führen Sie sphinx-quickstart mit dem Verzeichnis aus, das die Vorlagendatei enthält.

sphinx-quickstart --templatedir=my_sphinx_template

Conf.py wird jedoch nicht neu geschrieben, egal wie oft der Befehl ausgeführt wird. Andere Dateien wie "Makefile" werden neu geschrieben, aber "conf.py" wird nicht neu geschrieben. Lesen Sie daher die Quelle.

Der Code lautet wie folgt in Zeile 442 von 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())

Nur conf.py_t gibt die Dateien unter dem Paket direkt an.

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

Es ist zu unpraktisch, die Vorlage in "conf.py" nicht verwenden zu können, daher wird die Quelle neu geschrieben.

Über das Umschreiben der Quelle von Sphinx (2017-02-08 postscript)

Derzeit ist es ein Fehler, dass die Vorlagenfunktion für conf.py nicht funktioniert.

Die oben genannten Änderungen wurden übernommen und zusammengeführt und werden in 1.5.3 behoben, das Mitte März veröffentlicht wird. Ich habe zum ersten Mal eine Pull-Anfrage bei Github gestellt, aber ich habe viele Fehler gemacht, und ich möchte den Sphinx-Mitwirkenden danken, die bei mir waren.

Machen Sie Sphinx-Schnellstart bequem

Die Vorlage ist etwas schlampig, wird aber immer praktischer, da ich jedes Mal keine "conf.py" mehr bearbeiten muss. sphinx-quickstart ist ein Problem, das nicht mehr schnell ist, da die Anzahl der Elemente mit jeder Version zunimmt.

sphinx-quickstart hat verschiedene Optionen, so dass Sie eine Batch-Datei erstellen können, die alle Optionen anwendet, aber es ist sehr problematisch, weil es viele Optionen gibt.

Also werde ich ein Python-Skript schreiben, das den Schnellstart beschleunigt.

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]

#Feste Einstellung
d["version"] = "1.0"
d["language"] = "ja"

#Einfaches Makefile
d["make_mode"] = True

#Erweiterungseinstellungen
d["ext_mathjax"] = True

template_dir = "Vorlagenpfad oder Keine"

#Fragen, wenn Parameter fehlen (nicht erforderlich, wenn Sie möchten)
ask_user(d)

#Dokumentenerstellung
generate(d, templatedir=template_dir)

Bitte schreiben Sie den Inhalt selbst neu. Wenn Sie im obigen Beispiel den Projektpfad, den Projektnamen und den Autorennamen als Argumente ausführen, wird für alle anderen ein Dokument mit Standardeinstellungen erstellt.

Grundsätzlich wird das Dokument erstellt, indem das Parameterwörterbuch und das Vorlagenverzeichnis an die Methode sphinx.quickstart.generate übergeben werden. Es kann zweckmäßig sein, die Einstellungen mit Json in eine externe Datei zu verschieben oder ein Skript zu schreiben, das mit der GUI festgelegt wird.

Indem Sie dieses Skript- und Vorlagenverzeichnis intern freigeben, können Sie sofort eine benutzerdefinierte Dokumentgenerierung erstellen. Dies muss bequem sein.

2017-03-06 Nachtrag

Ich schrieb ich habe "sphinx-quickstart-plus" gemacht, um die Sphinx-Dokumentation bequemer zu machen, die Einstellung von conf.py in diesem Artikel ist Dies ist ein automatisch generiertes Tool.

Führen Sie einen automatischen Build mit sphinx-autobuild durch

Dies befreit Sie von der Mühe, beim Erstellen Ihrer Dokumentation "sphinx-quickstart" und "conf.py" zu bearbeiten. An diesem Punkt denke ich, dass es ziemlich praktisch ist.

Jedes Mal, wenn ich die Dokumentation aktualisiere und überprüfe, muss ich "make html" eingeben, aber wenn ich "sphinx-autobuild" verwende, wird sie automatisch erstellt.

Es kann mit pip installiert werden.

pip install sphinx-autobuild

Nach der Installation beginnt die Dateiüberwachung mit dem folgenden Befehl und wird gleichzeitig mit dem Update erstellt.

sphinx-autobuild  <Quellverzeichnis> <Erstellen Sie ein Artefakt-Ausgabeverzeichnis>

Dieser Befehl ist langwierig und jedes Mal umständlich einzugeben. Daher ist es hilfreich, dem generierten Makefile den folgenden Code hinzuzufügen.

Für Makefile


livehtml:
	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

Für neues Makefile


livehtml:
	sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html

Der folgende Befehl startet die automatische Build-Überwachung.

make livehtml

Greifen Sie mit localhost: 8000 auf das Dokument zu. Übrigens ist es praktisch, den entsprechenden Code mit der zuvor erwähnten Vorlagenfunktion zu "Makefile_t" und "Makefile.new_t" hinzuzufügen.

Fügen Sie die Vorlagen "Makefile_t" und "Makefile.new_t" in das Wesentliche ein.

https://gist.github.com/pashango2/399010efaa546a47db5c82c72e4f3b5e

Jupyter-Notizbuch importieren (hinzugefügt am 06.02.2017)

In letzter Zeit hat die Anzahl der Personen, die Dokumente mit Jupyter schreiben, zugenommen. Es gibt eine Sphinx-Erweiterung namens nbsphinx, mit der Sie Jupyter-Notizbücher erfassen können.

Die Installation ist mit pip einfach.

pip install nbsphinx

Bearbeiten Sie conf.py wie gewohnt.

conf.py


extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']

Stellen Sie sicher, dass die Erweiterung "nbsphinx" und das Ignoriermuster "**. Ipynb_checkpoints" enthalten.

Fügen Sie dann das Notizbuch zu "toctree" hinzu und schreiben Sie den Dateinamen ohne die Erweiterung ".ipynb". Bitte beachten Sie, dass die Überschrift (# title) in der ersten Zeile des Notizbuchs nicht erkannt wird, wenn Sie sie nicht in die erste Zeile des Notizbuchs einfügen.

Im folgenden Beispiel wird eine Datei mit dem Namen "jupyter.ipynb" als Dokument hinzugefügt.

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   jupyter

Jupyter Notebook wurde hinzugefügt! Es kann nützlich sein, der Vorlage "conf.py_t" auch "nbsphinx" hinzuzufügen.

jupyter.png