Recently we changed the format of the documentation of Zend Framework 2 from DocBook to reStructuredText. We used the Sphinx open source project ro render the documentation. Sphinx is a very powerful tool that is able to render the docs in many formats like Html, Pdf, ePub, etc.
This is the structure tree of the new documentation project of ZF2:
docs docs/Makefile docs/languages docs/languages/en/conf.py docs/languages/en/index.rst docs/languages/en/modules docs/languages/en/images docs/languages/en/ref docs/languages/en/tutorials docs/languages/en/user-guide docs/languages/en/_static docs/languages/en/_templates
The docs folder contains the entire documentation project. In the docs folder we have the Makefile that is used to render the docs using Sphinx.
The docs are translated in different languages under the docs/languages folder. For instance, the english documents are stored in the docs/languages/en folder.
Each language has the index.rst file that contains the Table Of Contents and the conf.py file, the configuration file for Sphinx.
The documents are stored in different subfolders according with the different contents. For instance, the documentation of the ZF2 components is stored in the modules folder (with the .rst extension).
The readthedocs.org website is an awesome project that renders the docs in HTML from a github repository on every update.
How to contribute
Contribute to the zf2-documentation project is very easy, you can fork the zendframework/zf2-documentation repository in github and send a Pull Request with your changes.
If you are not familiar with reStructuredText format we suggest to have a look at this reStructuredText Primer.
If you want to have a preview of your changes, you can render the documentation in HTML format on your computer. You have to install Sphinx and run the following command in the docs folder (these instructions are valid for GNU/Linux systems):
$ make html
The documentation will be generated in the _build/html subdirectory. By default, the make html command renders the documentation in English. To render in a different language you have to specify the LANG in the command line.
For instance, to render the documentation in Italian, execute the following command:
$ make html LANG=it
You can find the supported languages in the docs/languages subdirectory.
To simplify the collaboration process we added a very cool feature to edit the ZF2 documentation directly in the github website and send a PR using the browser! You can find a special button “Edit this document” that is visible at the bottom left on each page of the documentation (see the screenshot below).
You can click on this button and edit the document using the GitHub’s text editor.
The first time that you use the GitHub’s editor, if you didn’t fork the zf2-documentation project before, github will ask you to fork the project, click on “Create Fork”.
In order to use this editor you need to have an account on github. If you don’t have one you can create a new in a few second, sign here for a free account.
Fill in the “Commit” message text box at the end of the page telling why you did the changes. Press “Propose file change” button next to it when done.
On Send a pull request page you don’t need to fill in text anymore. Just press Send pull request button. Your changes are now queued for review under project’s Pull requests tab on GitHub.
We are very close to release the 2.0 version of Zend Framework and the documentation is a very important part. We are working to improve the docs but we need your help. So, what are you waiting for? Help out the project, yourself, and those trying to learn, and start writing and updating docs.
We look forward to have you as contributor of the project and thanks in advance for you help!