How to add documentation to the TYPO3 extension

Question

Is there a step-by-step guide on how to add documentation to the TYPO3 extension? I added two extensions to the repository, but I would like to add some documentation as well. In earlier times of the TYPO3 repository, it was pretty simple - as far as I remember, an OpenOffice document should have been added to the extension ... I found this "howto"

I use macOS Sierra and I installed a lot of things: Xcode, MacPorts, Sphinx, ...

I did all these pip installations

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

Error:

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

Excludes: File "conf.py", line 24, in import t3SphinxThemeRtd ImportError: There is no module named t3SphinxThemeRtd

The full trace was saved in / tmp / sphinx -err-bGi8t6.log if you want to inform the developers about it. Please also report this if it was a user error, so the best error message may be next time. A bug report can be sent to the tracker at https://github.com/sphinx-doc/sphinx/issues . Thanks!

So, the t3SphinxThemeRtd module was not found, although I added it using pip !?

Is there a simple method for adding documentation? I think this complicated procedure will force many developers to add documentation to their extensions !?

Answer 1

As already mentioned, you do not need to display the documentation locally, even if it can make life easier.

1. Using sphinx: if you want to write the first files, take a look at basic examples like https://github.com/georgringer/eventnews or https://github.com/sup7even/mailchimp/tree/master/Documentation

2. Separate files: but you can even write simpler documentation. Take a look at https://github.com/georgringer/page_speed/blob/master/README.rst, which is a separate file, and then https://docs.typo3.org/typo3cms/extensions/page_speed/ is also displayed.

3. Markdown: if you do not feel comfortable with relaxation, you can put README.md directly in the extensions directory, which is then displayed!

---

Full documentation on writing documents can be found here: https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html.

Answer 2

Christian, you are completely on the right track: Yes, give good documentation! More and more people really do. Therefore, I'm sure 2017 will be a year of breakthrough documentation.

In general, this is the minimum necessary: ​​add a file. /Documentation/Index.rst into the extension and write your documentation there. Use reStructuredText as markup.

Quickstart:

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

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

• Read the starter’s homepage to find out how it works.

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

• Edit directly on Github. Just do a small update and save (= push), and a few minutes later you can reload the page and see what the server has provided for you. You do not need to install or visualize it yourself. The server will do this for you.

• Or work with Github as usual.

• To become the owner of this project, send an email with you Github username to docteam at [e-mail] and ask for the T3DocumentationStarter project.

• Later: copy the folder. / Documentation project starter in extension. Write your documentation. Edit the metadata in. /Documentation/Settings.cfg and you're done.

Come to the sunny side of the documentation - have fun!

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

Answer 3

You do not need to configure Sphinx to write documentation. Documents are simple text files, so nothing should stop you there.

Sphinx is useful if you want to test your documentation. I have reported your mistakes to Martin Bles, who is responsible for the documents, and he will update the manual or contact you as soon as possible.

Answer 4

Do not create an OpenOffice document. You do not need to install sphinx locally! (although no one can stop you if you want). You can use the provided Docker image, which provides you with a complete working environment for rendering documentation.

The official documentation for writing documentation for extensions has been updated:

• How to run documentation for your TYPO3 extension

What documents do you need?

Your extension should have a Documentation directory, which should contain documentation in the form of reStructuredText (.rst) documents (for example, Index.rst). Markdowns are also supported. Alternatively, you can use a single-file solution (for example, only Readme.rst).

• Directories and file names

There are several options for creating extension documentation:

• There is an example extension guide . How to use this to run documentation from scratch is already described in the link I gave above.
• Or run rest files from scratch
• Or use existing extensions for inspiration, for example, int: form
• Or use the extension constructor (rename the Documentation.tmpl directory to Documentation).

How to edit .rst files

You can simply edit the files in a simple text editor or IDE (it is advisable to use an IDE with reStructuredText support, for example, for PhpStorm, use the reStructuredText plugin, use the LeXtudio reStructuredText plugin for Visual Studio code).

• Tip 1: read reStructuredText & Sphinx Introduction
• Tip 2. Use the reST & Crib Sphinx
• Tip 3: Read Common Mistakes to Avoid Mistakes

Render Render Files

If you want to check what your reST files will look like, you must display them locally.

You have several options for this , but it is recommended to use Docker.