Hello all, As I've previously talked about; I began to write a developer doc, stored on a github repository, and published on readthedocs. I'll tell you a bit more about my choices regarding this.
I've decided to use reStructuredText instead of markdown syntax (but not lateX). Why? Just because reST is another human readable format; but with many more possibilities than markdown to write real documentation. To me (and some others), markdown is cool, simple, ... But this this far from what we would need to write some docs. Using markdown for a GitHub's README.md file is really OK, no need for more; but this is not a documentation. At the opposite, using something like lateX would provide great results, but would be too complex for writing a documentation. reST offers many more possibilities... And therefore may be a bit more complex than markdown. But it is also well documented, used in many other projects, and several tools to help editing are available. I've used the Sphinx build system (http://www.sphinx-doc.org/), and facilities from both Github and Readthedocs to get the documentation built on every commit. Before I take a decision for developer doc, I took a look at daux (that has been used to write the new user documentation), and at "couscous" (another markdown formatting PHP system); and I've not been satisfied. Forgetting about markdown "poor syntax", both are quite complex to write a table of contents for example while Sphinx looks like more natural. And much more flexible also... Sphinx is fully compatible with reST, but also provides some specific markup (http://www.sphinx-doc.org/en/stable/markup/index.html#sphinxmarkup) that makes writing documentation easier. Note that sphinx is also capable to render markdown pages, it is for example compatible with the existing user documentation (mostly once links ave been linted) - but we cannot take advantage of reST or Sphinx facilities (like the TOC) in this case. I've also been very interested in the gettext translation that would be possible using Sphinx: http://www.sphinx-doc.org/en/stable/intl.html Another thing I like using is that it generates warnings while building the docs, that let us know if there are syntax issues, orphan pages (until they're explicitly declared as orphan), missing images, and so on. GLPi related publications I've made: - a Sphinx try on the existing user documentation: http://glpi-user-documentation.readthedocs.io/fr/sphinx/ (this is a 5" work, for a POC) - the developer documentation: http://glpi-developer-documentation.readthedocs.io/en/latest/ Some references: - full reST reference: http://docutils.sourceforge.net/rst.html - Sphinx docs: - Global: http://www.sphinx-doc.org/en/stable/index.html - TOC specific: http://www.sphinx-doc.org/en/stable/markup/toctree.html#toctree-directive - reST basics: http://www.sphinx-doc.org/en/stable/rest.html#rst-primer - Specific markup: http://www.sphinx-doc.org/en/stable/markup/index.html#sphinxmarkup - A "cheatsheet": http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html Tools: - retext editor: https://github.com/retext-project/retext - gedit plugin: https://github.com/bittner/gedit-reST-plugin - vim plugin: https://github.com/Rykka/riv.vim - more complete list: http://stackoverflow.com/a/2747041 Regards, -- Johan _______________________________________________ Glpi-dev mailing list Glpi-dev@gna.org https://mail.gna.org/listinfo/glpi-dev
