Über diese Seite

Die Seite wurde mit Sphinx (2.4.4) erstellt, dem Open-Source-Tool, das zur Erstellung der offiziellen Python-Dokumentation und vieler anderer Seiten verwendet wird. Dies ist ein sehr ausgereiftes und stabiles Tool und wurde unter anderem wegen seiner Unterstützung für die Definition von API-Elementen und deren Verknüpfung aus Code ausgewählt.

Die Seite verwendet ein benutzerdefiniertes Theme, das auf dem Read the Docs Theme basiert.

Die Seite durchsuchen

Die Suche liefert Themen, die alle der angegebenen Schlüsselwörter enthalten.

Tipp

Beginnen Sie immer mit der Suche nach einzelnen Wörtern wie „interacting“ oder „compiling“. Im Allgemeinen reicht dies aus, um das relevante Dokument zu finden. Wenn nicht, können Sie die Suche durch Hinzufügen weiterer Begriffe verfeinern.

Hinweis

Suchen, die Zeichen wie „-“ und „+“ enthalten, funktionieren nicht. Es gibt keine Unterstützung für logische Operatoren.

Fehler melden

Bitte melden Sie Dokumentationsfehler wie jeden anderen Emscripten-Fehler. Helfen Sie, diese zu beheben, indem Sie bestehende Dokumente aktualisieren oder neue erstellen.

Zur Seite beitragen

Beiträge zu dieser Seite (und tatsächlich zu jedem Teil von Emscripten) sind willkommen!

Lesen Sie den Rest dieses Artikels für Anweisungen zum Erstellen der Seite und zum Schreiben und Aktualisieren von Artikeln.

Die Seite erstellen

Die Quellen der Seite werden auf GitHub gespeichert. Bearbeitungen und Ergänzungen sollten auf dieselbe Weise in diesen Zweig eingereicht werden wie jede andere Änderung am Tool.

Die Seite wird auf dem emscripten-core/emscripten-site gh-pages Zweig (GitHub Pages) veröffentlicht.

Hinweis

Denken Sie daran, die Build-Version für öffentliche Builds zu aktualisieren.

Sphinx installieren

Diese Seite erfordert die Installation einer bestimmten Version von Sphinx. Führen Sie den folgenden Befehl aus, um sicherzustellen, dass Sie die richtige Version installiert haben

pip install -r requirements-dev.txt

Site-Builds

Die Seite kann unter Ubuntu und Windows aus dem Quellcode erstellt werden, indem Sie in das Verzeichnis /emscripten/site navigieren und den Befehl verwenden

make clean
make html

SDK-Builds

SDK-Builds sind praktisch identisch mit Site-Builds. Der Hauptunterschied besteht darin, dass bei SDK-Builds die Startseite eine klare Benachrichtigung enthält, dass es sich um einen SDK-Build handelt.

SDK-Builds werden aktiviert, indem das Tag sdkbuild aktiviert wird. Dies geschieht über die Umgebungsvariable SPHINXOPTS

# Set the sdkbuild tag.
set SPHINXOPTS=-t sdkbuild
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

Build-Version

Die Dokumentationsversion sollte der Emscripten-Version für den aktuellen Build entsprechen. Für einen allgemeinen Site-Build ist dies die neueste getaggte Version, wie in Emscripten-Version definiert. Für einen SDK-Build ist es die Emscripten-Version für das SDK.

Die Versions- und Release-Informationen werden an einigen Stellen in der Dokumentation verwendet, zum Beispiel AUTHORS.

Die Versionsinformationen sind in conf.py definiert — siehe die Variablen version und release. Diese Variablen können durch Setzen neuer Werte in der Umgebungsvariablen SPHINXOPTS überschrieben werden. Zum Beispiel, um die Variable release über die Befehlszeile unter Windows zu aktualisieren

# Set SPHINXOPTS
set SPHINXOPTS=-D release=6.40
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

Artikel schreiben und aktualisieren

Hinweis

Sphinx ist gut dokumentiert. Dieser Abschnitt versucht nur, spezifische Stile und Funktionen hervorzuheben, die auf dieser Seite verwendet werden.

Der Abschnitt Die Seite erstellen erklärt, wie man die Quellen für Artikel findet und die Seite erstellt.

Der Seiteninhalt wird mit reStructured Text geschrieben. Wir empfehlen Ihnen, die folgenden Artikel zu lesen, um die Syntax zu verstehen

Styleguide

Dieser Abschnitt enthält einige sehr kurze Empfehlungen, um Autoren bei der Verwendung eines gemeinsamen Stils zu unterstützen.

Tipp

In Bezug auf Beiträge schätzen wir Ihr Codieren und Schreiben von Inhalten viel mehr als perfekte Prosa! Geben Sie einfach Ihr Bestes und bitten Sie dann um eine redaktionelle Überprüfung.

Rechtschreibung: Verwenden Sie, wenn möglich, die US-amerikanische Rechtschreibung.

Vermeiden Sie Redewendungen: Diese können für Nicht-Muttersprachler besonders verwirrend sein (zum Beispiel bedeutet „putting your foot in your mouth“ tatsächlich „etwas Peinliches sagen“).

Hervorhebung

  • Fett: Verwenden Sie für Dateinamen und UI-/Menüanweisungen (zum Beispiel: „Drücken Sie OK, um etwas zu tun“).

  • Kursiv: Verwenden Sie für Toolnamen - z.B. Clang, emcc, Closure Compiler.

  • Monotype: Verwenden Sie für Inline-Code (wo Sie nicht auf die API-Referenz verlinken können) und zur Demonstration von Befehlszeilenoptionen des Tools.

Hinweis

Abgesehen von den oben genannten Regeln sollte die Hervorhebung sparsam verwendet werden.

Listen: Verwenden Sie gegebenenfalls einen Doppelpunkt am Anfang der Liste. Beginnen Sie jeden Punkt mit einem Großbuchstaben und schließen Sie ihn mit einem Punkt ab.

Arbeiten in Markdown

Neue Artikel können im Wiki unter Verwendung der Markdown-Syntax verfasst und diskutiert werden, bevor sie in die Dokumentation aufgenommen werden. Der einfachste Weg, diese in reStructured Text zu konvertieren, ist die Verwendung eines Tools wie Pandoc.

Hinweis

Das Tool get_wiki.py (/site/source/get_wiki.py) kann verwendet werden, um das Abrufen eines Snapshots des Wikis zu automatisieren. Es klont das Wiki und ruft pandoc für jede Datei auf. Die Ausgabe wird in einen Ordner wiki_static kopiert. Das Tool fügt außerdem eine Überschrift und einen Hinweis hinzu, dass die Datei ein „Wiki-Snapshot“ ist, und korrigiert Links, die als „Inline-Code“ markiert sind, zu passenden Links in der API-Referenz.

Read the Docs Theme

Die Seite verwendet eine Modifikation des Read the Docs Theme (dieses ist im Quellcode unter /emscripten/site/source/_themes/emscripten_sphinx_rtd_theme zu finden).

Die wichtigsten Änderungen am ursprünglichen Theme sind unten aufgeführt.

  • Footer.html

    • Urheberrecht geändert, um auf Emscripten-Autoren zu verlinken (einige Code-Teile wurden durch Übersetzungs-Markup beschädigt)

    • Fußzeilen-Menüleiste hinzugefügt

  • Layout.html

    • Kopfzeilen-Menüleiste mit Elementen hinzugefügt

  • Breadcrumb.html

    • Der Text des ersten Links wurde von „docs“ in „Home“ geändert.

    • Der Code „View Page Source“ wurde in die untere Fußzeile verschoben.

  • theme.css

    • Geändert, um 4 Ebenen Tiefe in der Sidebar-Inhaltsverzeichnis zu unterstützen.

    • Zentriertes Theme. Seitenleiste erreicht den Seitenfuß mittels absoluter Positionierung.

Site-Lizenz

Die Seite ist unter der gleichen Open-Source-Lizenz wie der Rest von Emscripten lizenziert. Mitwirkende an der Seite sollten sich zu AUTHORS hinzufügen.