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
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:
- 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