CODEWITHSUNDEEP
documentationtypo3
Christian Ehret
Christian Ehret

Reputation: 383

Howto add documentation to TYPO3 Extension

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!?

Upvotes: 7

Views: 413

Answers (4)

Sybille Peters
Sybille Peters

Reputation: 3229

Do not create an OpenOffice document. You do not need to install sphinx locally! (though no-one can stop you if you want to). You can use the supplied Docker image , which gives you a full working environment for rendering the documentation.

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

What documents do you need?

Your extension should have a directory Documentation in it, which should contain the documentation as reStructuredText (.rst) documents (e.g. Index.rst). Markdown is also supported. Alternatively, you can have a one-file solution (e.g. only Readme.rst).

For creating extension documentation there are several options:

  • There is an example extension manual. How to use this to start your documentation from scratch is already described in the link I gave above.
  • Or, start your ReST files from scratch
  • Or, use existing extensions for inspiration, e.g. ext:form
  • Or, use the extension builder (rename the Documentation.tmpl directory to Documentation).

How to edit the .rst files

You can just edit the files in a simple Text Editor or IDE (preferably use an IDE with reStructuredText support, e.g. for PhpStorm, use the reStructuredText plugin, for Visual Studio Code, use LeXtudio reStructuredText plugin).

Rendering the ReST files

If you want to test how your reST files will look, you should render them locally.

For this you have several options, but the recommended method is to use Docker.

Upvotes: 1

Georg Ringer
Georg Ringer

Reputation: 7939

As said, you don't need to render your documentation locally, even though it can make life easier.

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

  2. Single 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 single file and then rendered as well https://docs.typo3.org/typo3cms/extensions/page_speed/.

  3. Markdown: If you are not comfortable with rest, you can place a README.md directly into the extension directory, which is then rendered as well!

The full documentation for writing docs can be found here: https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html

Upvotes: 5

MartinBless
MartinBless

Reputation: 69

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 enter image description here

Upvotes: 6

Mathias Schreiber
Mathias Schreiber

Reputation: 334

You don't need to setup Sphinx to write documentation. The docs are plain textfiles, so nothing should stop you there.

Sphinx is helpful when you want to test your documentation, though. I reported your errors to Martin Bless, who is in charge of the docs and he will update the guide or get in touch with you asap.

Upvotes: 3

Related Questions