Bauproduktdokumentation mit MKDOCs

Es gibt eine beliebte Maxime, dass „ein Produkt so gut ist wie seine Dokumentation“. Dies gilt für Software genauso viel wie für physische Produkte.

Als kleiner Indie-Entwickler, der sich nicht auf Front-End-Design spezialisiert hat, beauftrage ich oft einen Freiberufler, um meine Produktwebsite zu erstellen-was natürlich normalerweise einen Dokumentationsbereich enthält.

Ein Dokumentationsabschnitt kann selbst für ein einfaches Produkt einige Zeit und Geld dauern, auch wenn es sich um ein einfaches Produkt handelt. Daher wäre es schön, das Rad für jeden Standort nicht neu zu erfinden. Zum Glück gibt es einen Weg.

Key Takeaways

• mkdocs ist ein kostenloser statischer Site -Generator, der sich ideal für die Erstellung von Projektdokumentation. Es ist leicht, einfach zu hosten und kann für eine eigenständige Site oder einen Dokumentationsabschnitt einer größeren Stelle verwendet werden.
• Um MKDOCs, Python und PIP (ein Python -Paket -Manager) zu verwenden, müssen auf Ihrem Computer installiert werden. MKDOCS ist lokal auf Ihrem Computer installiert, sodass Sie Ihre Dokumentation offline erstellen können.
• mkdocs ermöglicht eine Anpassung mit einer Vielzahl von Themen und der Möglichkeit, neue Seiten über die Konfigurationsdatei mkdocs.yml hinzuzufügen. Es enthält auch einen integrierten Webserver zur lokalen Vorschau der Dokumentation.
• mit MKDOCs erstellte Dokumentation kann auf Diensten wie GitHub -Seiten kostenlos gehostet werden und die DOCs oder auf Ihrem eigenen Server lesen. MKDOCs unterstützt auch die Bereitstellung auf diesen Plattformen direkt.

Einführung von Mkdocs

mkdocs ist ein kostenloser, statischer Site -Generator, der auf Bauprojektdokumentation ausgerichtet ist. Es kann verwendet werden, um eine eigenständige Website oder nur einen Dokumentationsabschnitt einer größeren Stelle zu generieren.

Da Mkdocs statische Dateien erzeugt, ist Ihre Dokumentation leicht und einfach zu hosten-nutzen Sie kostenlose Dienste wie Github-Seiten und lesen Sie die Dokumente-oder natürlich auf Ihrem eigenen Server.

In diesem Artikel stelle ich MKDOCs vor, zeigt Ihnen, wie Sie sie installieren, Dokumentationen erstellen und schließlich die generierte Dokumentation auf einem Webserver hosten.

Um die Art von Dokumentation zu erhalten, die MKDOCs erzeugt, schauen Sie sich meine ProfilePress -WordPress -Plugin -Dokumentation an, die mit MKDOCs unter Verwendung des DOCS -Themas erstellt wurde.

mkdocs ist in Python geschrieben. Die Dokumentationsquelldateien werden in Markdown geschrieben und mit einer einzelnen YAML -Konfigurationsdatei konfiguriert.

Um Dokumentationen mit MKDOCs zu erstellen, müssen Sie sie lokal in Ihrem Computer installieren lassen. Schauen wir uns also als nächstes an, wie es installiert wird.

Installieren von Python und Mkdocs

statische Site-Generatoren wie Jekyll (hauptsächlich zum Bloggen verwendet und auf Ruby aufgebaut) und MKDOCs benötigen einige Befehlszeilenkoteln. Seien Sie also gewarnt. Für diejenigen, die nicht daran gewöhnt sind, mit der Befehlszeile zu arbeiten, ermutige ich Sie, weiterzulesen und es auszuprobieren, da es nicht so schlimm ist, wie es aussieht!

installieren Sie Python und Pip

Um MKDOCs zu installieren, müssen Sie Python und Pip (einen Python -Paket -Manager) in Ihrem Computer installieren lassen. Sie können bereits auf Ihrem Computer installiert sein. Wenn Sie Python 3.4 oder später installiert haben, haben Sie wahrscheinlich PIP installiert. (Weitere Anweisungen finden Sie im Python -Installationshandbuch.)

, um Python auf einer Linux -Verteilung wie Ubuntu zu installieren

Laden Sie für Windows Ihren bevorzugten Versionsinstallationsprogramm herunter und führen Sie die Datei aus, um Python zu installieren.

Alternativ führen Sie den Schokoladential -Paket -Manager in Ihrem Computer installiert.

Um zu überprüfen, ob in Ihrer Python -Verteilung PIP installiert ist, führen Sie den Befehl PIP -Verssion aus. Andernfalls führen Sie Python Get-pip.py oder Choco PIP über Schokolade ein, um es zu installieren.

mkdocs

installieren

Jetzt, da Python und PIP installiert sind, führen Sie PIP -Installieren Sie MKDOCs aus, um MKDOCs zu installieren.

Um zu bestätigen, dass alles in Ordnung ist, führen Sie MKDOCs aus, um den Befehl mkdocs auszuführen.

Wenn Sie unter Windows sind und der Befehl mkdocs nicht am Leben ist, addieren Sie unbedingt C: Path-to-Python-Foldercripts zur Pfadumgebungsvariable.

Erstellen der Dokumentation

Jetzt, da Sie Python und Mkdocs eingerichtet haben, können Sie Ihre tatsächliche Dokumentation fortsetzen.

Erstellen Sie zunächst ein Projekt für die Dokumentation (nennen wir es SP-Doc) und navigieren Sie zum erstellten Ordner:

Der generierte Projektordner enthält einen DOCS -Ordner - in dem die Markdown -Dateien für die Dokumentation gespeichert werden - und die Konfigurationsdatei mkdocs.yml.

$ mkdocs new sp-doc
$ cd sp-doc

Hier ist die Verzeichnisstruktur:

Fügen Sie der mkdocs.yml-Datei die folgende Konfiguration mit nacktem Minimum hinzu:

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

mkdocs wird mit einer Reihe von Themen geliefert - wie "mkdocs", "Lesen Sie die Dokumente" und "Bootstrap". Sagen Sie, Sie beabsichtigen, das Standardthema zu verwenden. Ersetzen Sie in diesem Fall einfach Redethedocs durch mkdocs im obigen Code.

site_name: SitePoint Documentation
site_description: Description of the documentation
theme: readthedocs
pages:
- ['index.md', 'Index']

Die Seitenkonfiguration wird verwendet, um den Satz von Seiten zu bestimmen, die für die Dokumentation und das Navigationsmenü erstellt werden sollten.

zu den Seiten hinzugefügte Markdown -Dateien müssen relativ zum DOCS -Ordner sein. Wenn Sie beispielsweise einen neuen Ordner namens config in das docs -Verzeichnis erstellt und eine Setup.md -Datei hinzugefügt haben, finden Sie diese zu den Seiten in der Konfiguration von mkdocs.yml -Dateien:

Dies erstellt einige neue Seiten, die automatisch in unserem Dokumentationsmenü angezeigt werden. Erstens gibt es eine Seite mit Start.md mit dem Titel "Get Start".

site_name: SitePoint Documentation
site_description: Description of the description
theme: readthedocs
pages:
- ['index.md', 'Index']
- ['start.md', 'Get Started']
- ['config/setup.md', 'Configuration', 'Setup']
- ['config/debug.md', 'Configuration', 'Debug']

Wir haben auch einen neuen Abschnitt zum Dokumentationsmenü mit dem Namen "Konfiguration" hinzugefügt, unter dem ein Link zu neuen Setup- und Debug -Seiten besteht.

mkdocs enthält einen integrierten Webserver, sodass Sie Ihre Dokumentation lokal in der Vorschau anhand der Arbeiten in der Vorderseite in der Vorschau können.

, um den Webserver zu starten, sicherzustellen, dass Sie sich im Verzeichnis befinden, in dem sich die Konfiguration von Mkdocs.yml befindet, und dann den Befehl mkdocs dienen ausführen.

besuchen Sie http://127.0.0.1:8000 in Ihrem Browser, um die Dokumentation anzuzeigen:

Wenn Sie mit dem, was Sie erstellt haben, zufrieden sind, führen Sie MKDOCs Build aus, um die statischen Dateien für die Dokumentation zu generieren, die im Site -Verzeichnis gespeichert werden.

Sie können die statischen Dateien kopieren und auf einem Webserver Ihrer Wahl zur Live -Dokumentation hosten.

Im nächsten Abschnitt lernen wir, wie Sie MKDOCs bereitstellen, um die Dokumente und Github -Seiten zu lesen.

Bereitstellen von Mkdocs

Erstellen Sie zunächst ein GitHub- (oder Bitbucket) -Repository, um die Dateien zu speichern.

Führen Sie die folgenden Befehle aus, um sie in GitHub bereitzustellen, wobei https://github.com/collizo4sky/sitepoint_mkdocs mein eigenes MKDOCS -Repo ist:

$ mkdocs new sp-doc
$ cd sp-doc

Stellen wir nun unsere Dokumentationsdateien zum Lesen der DOCs, einen kostenlosen Dokumentationsdienst, bereit.

Lesen Sie die docs

Erstellen Sie zunächst ein Konto, wenn Sie keine haben, und melden Sie sich an.

Klicken Sie auf die Schaltfläche Ein Projekt importieren oder auf das Menüelement für das Projekt hinzufügen.

Sie können wählen, ob Sie Ihr GitHub- oder Bitbucket -Konto verbinden können, um die Dokumente zu lesen, um Ihr gesamtes Projekt zu importieren. Stattdessen werden wir mit der manuellen Einfuhr entscheiden, indem wir auf die Schaltfläche Projekt importieren.

füllen Sie das Formular wie im Bild unten gezeigt:

Wenn Sie die Dokumente erfolgreich aus GitHub importieren, werden Sie auf die Projektseite umgeleitet:

Sie können unsere generierte Dokumentation unter http://sitepoint-doc.readthedocs.org/en/latest/.

anzeigen

Wenn Sie die Dokumentation auf einem Subdomain möchten, weisen Sie einen CNAME -Datensatz in Ihrem DNS auf die Subdomain für Ihr Projekt auf.

Erstellen Sie beispielsweise die Dokumentation auf docs.sinepoint.com, um einen CNAME-Datensatz zu erstellen, der auf SitePoint-doc.readthedocs.org zeigt.

GitHub -Seiten

Schauen wir uns nun an, wie Sie unsere Dokumentation auf Github -Seiten, einen weiteren kostenlosen Hosting -Service, hosten.

Stellen Sie sicher

Führen Sie den Befehl mkdocs GH-Deploy-Clean

aus

Hinter den Kulissen erstellt dieser Befehl Ihre Dokumente und verpflichtet sie an den GH-Pages-Zweig und drückt dann den Zweig nach Github.

Hier ist eine Demo unserer SitePoint -Dokumente auf Github -Seiten.

Andere Anbieter

Jeder Hosting -Anbieter, der statische Dateien bedienen kann, kann verwendet werden, um eine von MKDOCs generierte Dokumentation zu erstellen. Die folgenden Richtlinien sollten eine allgemeine Unterstützung liefern.

Wenn Sie Ihre Site mit dem Befehl mkdocs erstellen, werden alle Dateien in das Verzeichnis geschrieben, das der Konfigurationsoption von Site_DIR (standardmäßig auf „Site“ “zugewiesen ist, in Ihrer mkdocs.yaml -Konfigurationsdatei.

Kopieren Sie einfach den Inhalt dieses Verzeichnisses in das Root -Verzeichnis des Servers Ihres Hosting -Anbieters und Sie sind fertig. Wenn Ihre Dokumente nur ein Unterabschnitt Ihrer Website sind, verschieben Sie die Dateien in einen bestimmten Unterordner.

Zusammenfassung

In diesem Tutorial haben wir gelernt, wie man Dokumentation mit MKDOCS, einem Python Static -Website -Generator erstellt, sowie wie man die Dokumentation kostenlos auf Github -Seiten bereitstellt und aufgibt.

Haben Sie schon einmal MKDOCs verwendet? Wenn nicht, würden Sie in Betracht ziehen, es zu verwenden? Wie gehen Sie derzeit damit um, Ihre Benutzer Dokumentation zu bedienen? Ich würde gerne Ihr Feedback hören oder alle Fragen beantworten, die Sie möglicherweise haben.

häufig gestellte Fragen (FAQs) zum Bauproduktdokumentation mit MKDOCs

Was sind die Voraussetzungen für die Verwendung von MKDOCs? MKDOCs unterstützt Python -Versionen 2.7, 3,5, 3,6, 3,7, 3,8 und Pypy. Sie können Ihre Python -Version überprüfen, indem Sie die Python -Version in Ihre Eingabeaufforderung eingeben. Wenn Python erfolgreich installiert ist, wird die Versionsnummer angezeigt. Wenn nicht, müssen Sie zuerst Python installieren. Nachdem Python installiert wurde, können Sie MKDOCs mit PIP, dem Python -Paket -Installateur, installieren. Geben Sie PIP ein, um MKDOCs in Ihrer Eingabeaufforderung zu installieren, um MKDOCs zu installieren. Das Standardthema heißt „MKDOCS“, aber es gibt viele andere Themen. Sie können das Thema ändern, indem Sie die Konfigurationsdatei mkdocs.yml bearbeiten. Ersetzen Sie MKDOCs im Abschnitt Thema durch den Namen Ihres gewünschten Themas. Einige Themen ermöglichen auch eine weitere Anpassung durch Hinzufügen einer benutzerdefinierten CSS oder einer JavaScript -Datei. Datei in Ihrem DOCS -Verzeichnis. Der Name der Datei wird als URL für die Seite verwendet. Fügen Sie dann einen neuen Eintrag zum Seitenabschnitt Ihrer Konfigurationsdatei mkdocs.yml hinzu. Das Format lautet - ["Seitentitel", "Dateiname.md"]. Der Seitentitel wird als Linktext im Navigationsmenü verwendet. Führen Sie einfach die MKDOCS GH-Deploy aus Ihrer Eingabeaufforderung aus, und MKDOCs erstellt Ihre Website und schieben Sie sie in den GHE-Seitenzweig Ihres Github-Repositorys. Wenn Sie für einen anderen Anbieter bereitgestellt werden möchten, müssen Sie die Site mit MKDocs Build erstellen und dann die Site -Dateien manuell hochladen.

Kann ich MKDOCs mit den Dokumenten lesen? Um MKDOCs mit Lesen der Dokumente zu verwenden, müssen Sie eine .readthedocs.yml -Konfigurationsdatei im Root Ihres Repositorys erstellen und MKDOCs als Dokumentationstyp angeben.

Wie aktualisiere ich MKDOCs? > Sie können MKDOCs aktualisieren, indem Sie PIP -Installation ausführen - MKDOCs in Ihrer Eingabeaufforderung. Dadurch wird die neueste Version von MKDocs heruntergeladen und installiert.

Kann ich MKDOCs für private Dokumentation verwenden? Wenn Sie jedoch die integrierte Github Pages-Bereitstellung verwenden, ist Ihre Dokumentation öffentlich zugänglich. Wenn Sie Ihre Dokumentation privat halten müssen, können Sie einen anderen Hosting -Anbieter verwenden, der den Kennwortschutz oder die Zugriffskontrolle unterstützt. Zu den Themen gehört eine integrierte Suchfunktion. Wenn Ihr Thema keine Suche oder einen anderen Suchanbieter verwenden möchten, können Sie Ihrer Konfigurationsdatei mkdocs.yml ein Such -Plugin hinzufügen. Dokumentation? Es gibt jedoch Tools und Dienste von Drittanbietern, die Ihre MKDOCS-Site in ein PDF umwandeln können. Aus dem Seitenabschnitt Ihrer Konfigurationsdatei mkdocs.yml. Jeder Eintrag im Abschnitt "Seiten" wird zu einem Link im Navigationsmenü. Die Reihenfolge der Links entspricht der Reihenfolge der Einträge im Abschnitt der Seiten.

Das obige ist der detaillierte Inhalt vonBauproduktdokumentation mit MKDOCs. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!