Howto add documentation to TYPO3 Extension

Question

Is there a step by step manual how to add documentation to a TYPO3 extension? I added two extensions to the repository but I would like to add some documentation, too. In earlier times of the TYPO3 repository this was quite easy - as far as I can remember a OpenOffice document had to be added to the extension... I found this "howto"

I'm using macOS Sierra and I installed a lot of stuff: Xcode, MacPorts, Sphinx,...

I did all these pip installs

But calling make in the _make directory of the documentation directory of github.com/marble/typo3-docs-typo3-org-resources gives me the following

error:

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 the module t3SphinxThemeRtd was not found although I added it with the pip command!?

Is there not an easy method to add a documentation? I think this complex procedure will stop many developers to add a documentation to their extensions!?

Answer 1

Christian, you are totally on the right track: Yes, provide some good documentation! More and more people really do. So I'm sure, 2017 will be THE year of documentation breakthrough.

In general this is the minimum needed: Add a file ./Documentation/Index.rst to your extension and write your documentation in there. Use reStructuredText as markup.

Quickstart:

To have a better start with more bells and whistles this is what you really should do at the moment:

• Get yourself one of the T3DocumentationStarter projects that look like https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-000/.

• Read the frontpage of the starter to learn how it works.

• For example, this one is reserved for you: https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-041/

• Edit directly at Github. Just do a little update and save (=push), and some very few minutes later you can reload the page and see what the server has rendered for you. You don't have to install or render anything yourself. The server will do that for you.

• Or work with Github as you usually do.

• To become the owner of that project send a mail with you Github username to the docteam to [email protected] and ask for a T3DocumentationStarter project.

• Later: Copy the ./Documentation folder of the starter project to your extension. Write your documentation. Edit the metadata in ./Documentation/Settings.cfg and you are done.

Come to the sunny side of documentation - have fun!

PS: Now on https://docs.typo3.org/Tips/TipOfTheDay/Index.html#how-to-start-documentation-for-your-typo3-extension as well