Um loszulegen: https://agenatrader.github.io/AgenaScript-documentation-de/index.html
MkDocs ist ein schneller, einfacher und regelrecht wunderschöner Generator von statischen Webseiten, der auf den Aufbau von Projektdokumentation ausgerichtet ist. Quelldateien einer Dokumentation werden im Markdown Format geschrieben und mit einer einzigen YAML-Konfigurationsdatei konfiguriert. Die Tutorials im Quellenverzeichnis dieses Repositorys werden mit mkdocs gebaut und auf GitHub Pages öffentlich gehostet unter https://github.com/AgenaTrader/AgenaScript-documentation
Diese Beschreibung wird Ihnen zeigen, wie Sie statische Webseiten erstellen und diese auf das Live-System übertragen.
Um diese Dateien zu editieren, können Sie den GitHub Online Editor verwenden, wir empfehlen aber, einen gesonderten Text-Editor zu verwenden. Wir empfehlen den Text-Editor Atom. You can download it here.
Folgende Dinge sind Voraussetzung:
- Installieren Sie GitHub Client, erstellen Sie einen GitHub-Benutzer und schauen Sie sich das Repository an
- Installieren Sie Python
- Installieren Sie das Python-Paket mkdocs anhand von pip
- Installieren Sie Pandoc
Nach Installation aller Pakete können wir anfangen, die Daten zu analysieren und unsere Seite einzusetzen.
Klonieren Sie das Haupt-Repository auf ihrem lokalen Rechner. Da wir jetzt alles in der richtigen Stelle haben, werden wir Dateien modifizieren und die neue Seite einführen. Im Folgenden sehen Sie eine ausführliche Beschreibung, wie Sie Daten in der GH Pages-Seite erstellen und einsetzen. Falls Sie keine Zeit haben, schauen Sie einfach direkt auf Short version on how to deploy
Folgenden Schritt müssen Sie nur dann ausführen, wenn der GH Pages-Zweig noch nicht zuvor erstellt wurde. Unsere statische Webseite wird über den GH Pages-Zweig dargestellt. Daher müssen wir den Zweig erstellen, indem wir folgende Befehle mithilfe der Befehlszeile verwenden.
git checkout master # you can avoid this line if you are in master
git subtree split --prefix output -b gh-pages # create a local gh-pages branch containing the splitted output folder
git push -f origin gh-pages:gh-pages # force the push of the gh-pages branch to the remote gh-pages branch at origin
git branch -D gh-pages # delete the local gh-pages
Alle sich in diesem Repository befindlichen Dokumente sind im Markdown-Format geschrieben und werden im Quellenverzeichnis dieses Repositorys aufbewahrt. Um diese Markdown-Dateien in statische Webseiten zu parsen, brauchen wir mkdocs, um diese Arbeit für uns zu erledigen. mkdocs wird diese Markdown-Dateien parsen, diese in statische Webseiten übertragen und dann im Site-Verzeichnis aufbewahren. Die gesamte Konfiguration wird in einer einzigen YAML configuration file ausgeführt, um den Analysevorgang zu konfigurieren. Öffnen Sie Console, navigieren Sie zu Ihrer YAML-Konfigurationsdatei und bauen Sie die Markdown-Dateien anhand des mkdocs-
mkdocs build
Dies wird ein neues Verzeichnis mit dem Namen site erschaffen.
Falls Sie eine Warnung bekommen, dass das site-Verzeichnis schon erstellt wurde, können Sie das clean
Parameter verwenden, um dieses Verzeichnis zu löschen, bevor Sie diese neu erschaffen.
mkdocs build --clean
Öffnen Sie nun den Ordner „Dokumente“ und modifizieren Sie das Freigabedatum in der epub_title.txt Datei. Danach navigieren Sie zu Ihrem Quellordner, öffnen Sie eine Console und erstellen Sie ein Ebook im *.epub Format:
pandoc -S --epub-cover-image=../documents/epub_cover.png --epub-stylesheet=../documents/epub_styles.css -o ../documents/agenascript-documentation.epub ../documents/epub_title.txt index.md handling_bars_and_instruments.md events.md strategy_programming.md keywords.md drawing_objects.md hints_and_advice.md
Wir empfehlen, mithilfe von pagina EPUB-Checker das Ebook zu validieren. You can download it here.
Navigieren Sie zu Ihrem Quellordner, öffnen Sie eine Console und erstellen Sie ein Word-Dokument im *.docx Format:
pandoc -S -o ../documents/agenascript-documentation.docx ../documents/epub_title.txt index.md handling_bars_and_instruments.md events.md strategy_programming.md keywords.md drawing_objects.md hints_and_advice.md
Falls Sie tags in Ihrer Markdown-Datei verwenden, erstellt mkdocs falsche Links für diese Bilder, deswegen müssen wir dies ändern, indem wir ** ./media/ to ../media/** manuell ersetzen.
Eine weitere Option besteht darin, dies automatisch anhand von sed auf Linux oder Macintosh zu machen:
sed -i .bak -e 's%./media/%../media/%g' site/drawing_objects/index.html && rm site/drawing_objects/index.html.bak
sed -i .bak -e 's%./media/%../media/%g' site/events/index.html && rm site/events/index.html.bak
sed -i .bak -e 's%./media/%../media/%g' site/handling_bars_and_instruments/index.html && rm site/handling_bars_and_instruments/index.html.bak
sed -i .bak -e 's%./media/%../media/%g' site/hints_and_advice/index.html && rm site/hints_and_advice/index.html.bak
sed -i .bak -e 's%./media/%../media/%g' site/keywords/index.html && rm site/keywords/index.html.bak
sed -i .bak -e 's%./media/%../media/%g' site/strategy_programming/index.html && rm site/strategy_programming/index.html.bak
Wir haben schon einen Zweig namens gh-pages erstellt, alle Daten von diesem Zweig werden auf GitHub Pages angezeigt.
Der neueste Einsatz dieser Dokumentation wurde mit mkdocs version 0.16.0 (2016-11-04) erstellt. Bitte verwenden Sie folgendes Befehl, um Ihre mkdocs-Version nachzuprüfen.
mkdocs --version
Wenn Sie eine ältere mkdocs-Version betreiben, verwenden Sie bitte folgendes Befehl, um auf eine neuere Version zu aktualisieren.
pip install --upgrade mkdocs
Erstellen Sie einen Commit und schicken Sie all Ihre Änderungen ins Haupt-Repository, dann synchronisieren Sie mit Ihrem entfernten Repository.
Nun sind wir bereit, folgendes Shell-Script auszuführen, um die Webseite aus unseren Markdown-Dateien zu bauen.
./buildanddeploy.sh -build
Nun ist es Zeit, den neuen Aufbau im Haupt-Repository festzulegen. Erstellen Sie einen Commit, schicken Sie all Ihre Änderungen ins Haupt-Repository und synchronisieren Sie mit Ihrem entfernten Repository.
Ist der Bauprozess fertig, können wir damit anfangen, die Webseite zum gh-Zweig unseres entfernten Repositorys einzusetzen.
./buildanddeploy.sh -deploy
Glückwünsche! Wir sind fertig. Alle Änderungen sind nun auf GitHub Pages online.