ZF2 documentation project, We Want You!

August 2, 2012

News, Zend Framework

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.

We decided to move the documentation from the zendframework/zf2 github repository to a new one: zendframework/zf2-documentation.

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).

We published the documentation online in our packages web site (packages.zendframework.com) and also in the readthedocs.org website (zf2.readthedocs.org).

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!

,

Trackbacks/Pingbacks

  1. Codigolinea » Pasos para Traducir la Documentación de ZF2 - September 21, 2012

    [...] Seleccionamos nuestro branch “traduccion” y rellenamos el formulario poniendo información de los cambios que hemos hecho y lo enviamos presionando el botón “Send pull request” y listo!!!! información adicional sobre la traducción. http://devzone.zend.com/2463/zf2-documentation-we-want-you/ [...]

Leave a Reply

You must be logged in to post a comment.