Hi Thomas, Valerio, Sphinx looks nice indeed, but the need to replicate what's in the code bothers me: if you change the API, devs can forget to change the documentation, leading to mismatch between code and docs.
I would prefer using qdoc / doxygen as they allow documenting code directly as comments. (IMO) qdoc is rather clumsy to use, and doxygen produces better docs, so I would go for the latter. The only problem about doxygen is that it don't handle QML components nicely out of the box, so we need 3rd party plugins like doxyqml [1]. Regards, Lucien [1] http://agateau.com/2013/introducing-doxyqml/ ----- Mail original ----- De: "Thomas Perl" <th.p...@gmail.com> À: mer-general@lists.merproject.org Envoyé: Lundi 8 Décembre 2014 14:06:55 Objet: Re: [mer-general] Mer/Nemo docs for new packages ? Hi, 2014-12-06 12:54 GMT+01:00 Valerio Valerio <vdv...@gmail.com>: > currently there are no guidelines regarding new documentation for Mer/Nemo > modules(afaik), upstream projects use different tools for that, but IMO > would be nice to have same style for the modules originated from Mer/Nemo, > not trying to enforce any documentation tool here, but since code is mostly > Qt, qdoc template would make sense to begin with(other could follow if > needed), also there's no need to change the packages already having docs > made with tools other than qdoc. > > Opinions ? Something like Sphinx[1] maybe? It can do HTML, PDF, ePub and some other formats out of the box, has nice markup based on reStructuredText[2] and there are some nice templates out there, and even web services[3] that build documentation directly from Git, and can keep around documentation for a given Git tag or the master branch, all automatically (you can also easily build it locally with “make html” in the docs directory). An example I’ve done a few months ago: The HTML documentation: http://nemo-qml-plugin-dbus.readthedocs.org/en/latest/ The markup source: https://raw.githubusercontent.com/nemomobile/nemo-qml-plugin-dbus/master/docs/index.rst There are lots of projects[4] using Sphinx already, and while it’s mostly projects with a Python background (the official Python documentation[5] is also done using Sphinx), projects like OpenCV and Varnish Cache also use it and are not Python-based projects. If you go with qdoc, at least provide some tooling, templates and build files so that it’s easy to write a simple documentation file without much boilerplate code (the docs/ directory[6] in the Nemo QML D-Bus Plugin has 3 files, “Makefile” and “conf.py” are generated by sphinx-quickstart, and you only need to write the index.rst file, theme/template code is not kept with the project, only referenced in the config) and easy to update the template style without having to apply the changes to every source repository. Bonus points for being able to build the documentation right from a Git checkout on a normal Debian/Fedora/OS X install without having to install the Mer SDK (makes the barrier to entry lower for potential documentation contributors). There’s also been some discussion in June about documentation tools and autodoc[7] that might be worth reading. HTH :) Thomas [1] http://sphinx-doc.org/ [2] http://docutils.sourceforge.net/rst.html [3] https://readthedocs.org/ [4] http://sphinx-doc.org/examples.html [5] https://docs.python.org/3/ [6] https://github.com/nemomobile/nemo-qml-plugin-dbus/tree/master/docs [7] http://merproject.org/meetings/mer-meeting/2014/mer-meeting.2014-06-24-08.44.log.html#l-407
