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:

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: 

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: 
  - reST basics: http://www.sphinx-doc.org/en/stable/rest.html#rst-primer
  - Specific markup: 
- A "cheatsheet": 

- 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


Glpi-dev mailing list

Reply via email to