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
