Login/Register
Howto add documentation to TYPO3 Extension
Asked Answered
Solved documentationtypo3
B

4

7

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

Brundage answered 29/12, 2016 at 17:11 Comment(1)
The official documentation has been updated. You can go straight to docs.typo3.org/typo3cms/HowToDocument/WritingDocForExtension/… – Stumpf
P
5

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

Pajamas answered 29/12, 2016 at 18:35 Comment(1)
Addition to 3. Look at docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/… for supported file names and formats – Stumpf
C
6

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

Croner answered 29/12, 2016 at 21:8 Comment(1)
This answer is outdated. Using the T3DocumentationStarter projects is currently no longer supported. The recommended method to test the rendering is to use Docker locally or use a documentation-draft branch. See docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/… – Stumpf
P
5

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

Pajamas answered 29/12, 2016 at 18:35 Comment(1)
Addition to 3. Look at docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/… for supported file names and formats – Stumpf
R
3

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.

Reprehensible answered 29/12, 2016 at 18:5 Comment(0)
S
1

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.

Stumpf answered 8/12, 2017 at 15:39 Comment(0)

© 2022 - 2024 — McMap. All rights reserved.