Dokumentation zur TYPO3 Extension hinzufügen

Question

Gibt es eine Schritt für Schritt Anleitung, wie man Dokumentation zu einer TYPO3 Extension hinzufügt? Ich habe dem Repository zwei Erweiterungen hinzugefügt, aber ich möchte auch etwas Dokumentation hinzufügen. In früheren Zeiten des TYPO3 Repository war dies ganz einfach - so weit ich ein Openoffice-Dokument an die Erweiterung werden mußte erinnern kann hinzugefügt ... ich diese "howto"

fand ich bin mit macOS Sierra und ich installierte eine Menge Sachen: Xcode, MacPorts, Sphinx, ...

ich habe im _make Verzeichnis der Dokumentationsverzeichnis machen von these pip installs

Aber rufen alle github.com/marble/typo3-docs-typo3-org -resources gibt mir die folgenden

Fehler:

sphinx-build -b html -d build/doctrees -c . -a -E -w ./_not_versioned/warnings.txt .. build/html Running Sphinx v1.5.1

Exception occurred: File "conf.py", line 24, in import t3SphinxThemeRtd ImportError: No module named t3SphinxThemeRtd

The full traceback has been saved in /tmp/sphinx-err-bGi8t6.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at https://github.com/sphinx-doc/sphinx/issues . Thanks!

So das Modul t3SphinxThemeRtd nicht gefunden wurde, obwohl ich es mit dem Pip-Befehl hinzugefügt !?

Gibt es keine einfache Methode zum Hinzufügen einer Dokumentation? Ich denke, dass diese komplexe Prozedur viele Entwickler daran hindern wird, ihren Erweiterungen eine Dokumentation hinzuzufügen !?

Answer 1

Wie gesagt, Sie müssen das nicht lokal analysieren, auch wenn es das Leben leichter machen kann.

1. Mit Sphinx: Wenn Sie rst Dateien zu schreiben, werfen Sie einen Blick auf grundlegenden Beispielen wie https://github.com/georgringer/eventnews oder https://github.com/sup7even/mailchimp/tree/master/Documentation

2. Einzelne Dateien: Sie können aber auch einfachere Dokumentation schreiben. Werfen Sie einen Blick auf https://github.com/georgringer/page_speed/blob/master/README.rst, die eine einzelne Datei ist und dann auch gerendert https://docs.typo3.org/typo3cms/extensions/page_speed/.

3. Markdown: Wenn Sie mit dem Rest nicht vertraut sind, können Sie eine README.md in das Erweiterungsverzeichnis bitte, die dann auch gemacht wird!

---

Die vollständige Dokumentation zum Schreiben docs hier gefunden werden kann: https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html

Answer 2

Sie müssen Sphinx nicht einrichten, um Dokumentation zu schreiben. Die Dokumente sind einfache Textdateien, also sollte Sie nichts dort aufhalten.

Sphinx ist hilfreich, wenn Sie Ihre Dokumentation testen möchten. Ich habe Ihre Fehler an Martin Bless gemeldet, der für die Dokumentation verantwortlich ist. Er wird den Leitfaden aktualisieren oder sich so schnell wie möglich mit Ihnen in Verbindung setzen.

Answer 3

Christian, Sie sind völlig auf dem richtigen Weg: Ja, einige gute Dokumentation zur Verfügung stellen! Immer mehr Menschen tun es. Ich bin sicher, 2017 wird DAS Jahr des Dokumentationsdurchbruchs sein.

Im Allgemeinen Dies ist das Minimum erforderlich: Fügen Sie eine Datei ./Documentation/Index.rst zu Ihrer Erweiterung und schreiben Sie Ihre Dokumentation dort. Verwenden Sie reStructuredText als Markup.

Schnellstart:

Um eine bessere haben mit mehr Schnickschnack diesem Start ist, was Sie wirklich im Moment tun sollte:

• sich eine der T3DocumentationStarter Projekte erhalten, die aussehen wie https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-000/.

• Lesen Sie die Vorderseite des Starters, um zu erfahren, wie es funktioniert.

• Zum Beispiel ist dies für Sie reserviert: https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-041/

• Bearbeiten direkt auf Github. Mach einfach ein wenig update und speichere (= push), und einige Minuten später kannst du die Seite neu laden und sehen, was der Server für dich gerendert hat. Sie müssen nichts selbst installieren oder rendern. Der Server wird das für Sie tun.

• Oder arbeiten Sie wie gewohnt mit Github.

• an den Eigentümer des Projekts werden eine E-Mail mit Ihnen Github Benutzername zum docteam für ein T3DocumentationStarter Projekt documentation@typo3.org und fragen senden.

• Später: Kopieren Sie den ./Documentation-Ordner des Starter-Projekts in Ihre Erweiterung. Schreiben Sie Ihre Dokumentation. Bearbeiten Sie die Metadaten in ./Documentation/Settings.cfg und Sie sind fertig.

Kommen Sie auf die Sonnenseite der Dokumentation - viel Spaß!

PS: Jetzt auf https://docs.typo3.org/Tips/TipOfTheDay/Index.html#how-to-start-documentation-for-your-typo3-extension auch