Hi guys, There are bridges between Sphinx and doxygen, e.g. [1], if you like the RST format and self documenting code in C++.
BR, Dima [1] http://breathe.readthedocs.org/en/latest/ 2014-12-08 15:17 GMT+02:00 <[email protected]>: > 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" <[email protected]> > À: [email protected] > 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 <[email protected]>: > > 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 > > > > >
