#24 Integrate documentation into code

[Vukics, András]

The documentation of the API (“reference manual”) should be integrated into the code in Doxygen-style.

Rationale: better maintainability, easier acces to code for outsiders, doxygen integrates better with C++ than Sphinx

Then, the detailed documentation can be created by doxygen, while the tutorials, main page, etc. can remain in Sphinx. Eventually, a bridge between the two might be created by breathe.

Preferred format:
/// Brief description.
/** Detailed description. */

As a general guideline, the brief description could be placed before the declaration (in the header file) and the detailed description before the member definition (in an implementation file).

[Vukics, András]

Such functions and classes as are automatically declared/defined (by the preprocessor, e.g. in reentrant headers) can be documented using the structural commands like \fn, \class, etc.

[Raimar Sandner]

I was looking at how to reference external doxygen projects. The key here is to create a tag file, which then can be loaded by other documentation projects.

However there is a problem: I created such a tag file by setting GENERATE_TAGFILE = core.tag in Doxyfile.in. The resulting file build/core.tag is not valid xml. For example, in line 3684 there is a <compound kind="namespace"> tag which is never closed.</compound>

I noticed this when I tried to build some cpypyqed documentation with sphinx and cross-link to the doxygen documentation with doxylink, which failed because the core.tag file could not be parsed. I'm sure this will also be an issue when other parts of the project (elements, scripts) have their own doxygen documentation which should be cross-referenced with the core.

For the cpypyqed documentation, sphinx seems to be the only practical choice without having much overhead. The advantage here is that sphinx takes the documentation from the built python modules and their docstrings, which works quite nicely already apart from cross-references to doxygen. I really don't know how this could be done with doxygen directly. I think with doxygen I would have to document every single wrapped class and function manually.

[Vukics, András]

I’ve been also experimenting with tagfiles recently in my doxygen branch, and I also get a tag mismatch fatal error when doxygen tries to access core.tag from elements. Despite this, I haven’t noticed any problem with cross-referencing.
It must be a bug in doxygen.
Documenting cpypyqed with sphinx is fine with me, if we can get it cross-referenced with the doxygen part.

[Raimar Sandner]

This is the culprit:
https://bugzilla.gnome.org/show_bug.cgi?id=712743
Indeed, setting INLINE_SIMPLE_STRUCTS = NO produces a valid core.tag xml file. Any objections against this setting until the bug is resolved?

[Vukics, András]

None whatsoever, especially since it’s not too relevant in our case.

[Raimar Sandner]

Hi András, do you get noticed about comments I make in gitlab? Otherwise I will write you an email if I comment...

One solution is to copy technicalDefinitions.sty to CPPQEDelements/doc.

Another solution is to move this file to the super-repository, where we could create a doxygen document linking to the subprojects. I could set this up if you want. The disadvantage would be that the documentation could only be built in the monolithic project layout.

Please also note my commit [a50969] which restores the appearance of dependency graphs as it was before the documentation was built by cmake.

[Vukics, András]

Cf. my comment.

So far, I haven’t got notifications about comments in gitlab, but now I set my notification settings for the CPPQED group to “watching”, so hopefully I will.

[Raimar Sandner]

You can also use "Participating", so you will only get notifications about your own resources. Otherwise you will be notified about every push, which might be a bit noisy.

[Raimar Sandner]

Currently I'm working on some layout for the documentation, and I'm almost done. There are a few things to consider:

• Building and viewing the documentation should work regardless of which project layout is used (monolithic or standalone, installed or build-tree).
• It follows that core has to announce the doxygen path as part of find_package(CPPQED), just using a relative path within elements will not work
• Installing the documentation to a different location (that includes also building the html tree for online browsing) probably will only work in monolithic layout: only then it is guaranteed that relative paths from elements pointing to core stay valid, because everything is installed or relocated together
• In any case absolute paths in the output have to be avoided. That is: grep -r $HOME * must return nothing in any html dir.

[Raimar Sandner]

Please have a look at the current head, where the points above are implemented.

Note that the doc target moved to the super repository, the project doc targets are now named core_doc and elements_doc.

Also the docs are now built in the top level build directory under doc/${PROJECT_NAME}. This ensures that for monolithic builds everything is contained in a single doc directory, with relative paths between the sub projects.

[Vukics, András]

Seems to work fine with me.

[Raimar Sandner]

Here is the first draft of a cpypyqed documentation, including links to doxygen. Entry point is doc/cpypyqed/html/index.html

[Raimar Sandner]

I have added documentation to the super-repository (make doc in the super repository). Entry point is <build-dir>/doc/html/index.html. I read in core.tag in this doxygen project, which causes the sections from core to appear in the navigation panel. Do you know why this is the case, and is it desired?</build-dir>

In the top-level documentation I have started documenting the test suite. At the moment, there is a short user guide documenting the several possibilities to run the test suite. A guide how to write new tests will follow.

[Vukics, András]

Thanks again for all this great work.

Yes indeed, I also noticed this case with the sections because the same occurs when I link to core.tag from elements. I don’t know why this is, and I wouldn’t say it’s desired, to me it seems rather undesirable. Perhaps it can be configured away somehow?

I looked through the cpypyqed documentation, and the format seems all right to me. I see you managed to link to the doxygen documentation of core and elements.
Incidentally, the syntactic sugar of this expression:
makeComposite({(0,2):poc,(0,1):poc})
is very impressive :) .

[Raimar Sandner]

The documentation of the test suite now contains (hopefully sufficient detailed) descriptions of the two test drivers (python and boost) and how to
add new tests which are run by one of these test drivers.

[Raimar Sandner]

The problem with the external pages showing in the sidebar is solved by setting EXTERNAL_PAGES to no, which I have done.

There is now a main page for the core and cppqed documentations. And if the documentation is built in monolithic mode, there is an additional navigation panel in the header linking to all the different projects.

[Vukics, András]

Very nice indeed! Now, all we need is a bit more work on the substance of the documentation and a nicer skin for doxygen.

[Raimar Sandner]

Cleaned up the cmake stuff, there is a new cmake macro cppqed_documentation to avoid cmake code duplication.
As a consequence, for consistency, the Doxyfile.in is now in doc/Doxyfile.in for all the projects.

At the moment I'm working on a documentation of the build system itself. This has become quite complex over time, and it would be good to have it documented for later reference.

[Vukics, András]

Exactly, and I expect that some of it will have to end up in the installation guide as well.

[Raimar Sandner]

I added cmake documentation in the super-project (private repository).

• on the user level ("The cmake build system" page)
• full reference targeted to build system developers (entry point is either the "Module" or the "Files" page)

It is not complete yet, but large parts are covered already.

[Raimar Sandner]

I added a detailed reference documentation for the Python test driver. This should aid in writing new test classes and using the existing ones.

Entry point is the "Test suite" module in the doxygen configuration.