Human-made documentation (not Doxygen) about grid

[coppolachan]

Clang doc could be another option: https://jessevdk.github.io/cldoc/

I like the CMS idea but how is that different from doxygen? after a, very quick, first look seems pretty similar to me.

[aportelli]

Yes it is quite different from Doxygen and the Clang doc you are proposing. Sphinx is just a framework to build a website, specially targeted at documenting code. But it does not generate automatically pages based on the code which I believe is the main purpose of Doxygen.

I was proposing that because a "human-made" documentation can be much more concise and to the point that a generator like Doxygen that will parse the entire code. I was really thinking it about a more dynamic alternative to a LaTeX document.

[coppolachan]

by looking at a couple of examples I had the idea of a human created content + the actual documentation of the function/classes/... done in a somewhat automatic way from the code.
We need the second part if we want to avoid obsolescence in my view or we are still in the case of a pdf, with hyperlinks.
Happy to use Sphinx but both segments can be done with doxygen in any case. We had a tutorial part in our doxygen iroiro documentation, for example http://suchix.kek.jp/guido_cossu/documents/DoxyGen/html/Using.html

[aportelli]

This might be a bit of a personal taste, but I actually do not quite like the fact that Doxygen requires you to write the documentation in the code. My personal experience is that I found painful to read headers from other codes that were completely scattered due to Doxygen text within the code.
I was more inspired by something like the QDP++ PDF documentation that I found very short and efficient. But you might have more experience with Doxygen and think that we can achieve the same thing with it? For example, is it possible to write Doxygen pages without actually putting comments in the code (i.e. in Markdown/HTML or something)?

[coppolachan]

I do understand your concern. I personally find documentation in the code quite useful but it is not mandatory for me, we could ask around for the preference in the community to have a better idea. At the end the documentation is for the users.

I used doxygen markup language to create the pages in the link I posted. Of course those are manually created but can point to the automatically generated pages from the code quite easily (essentially by name matching).
We used a single file but that can be separated in several ones
https://github.com/coppolachan/IroIro/blob/master/lib/Main/documentation_pages.h
I did not try to create a latex pdf version of this but should be fine and QDP like, I think.

Again, doxygen is not necessary but I find it better integrated to the automated documentation that can be browsed, and that saved my life when managing to understand chroma and all the templates scattered in the code (not too different from Grid in this respect).

[paboyle]

Personally, I think we do need a PDF or similar with human generated design philosophy.
Just a question of when, not if.

[coppolachan]

PDF (or web pages) on the design choices and general ideas behind the structure is needed, that is sure, I think everyone agrees on that.
Let's discuss when, how and if we need a commented code that can be browsed.

[paboyle]

I promised carleton I would produce some form of documentation this quarter.

[paboyle]

Closing until someone reads the documentation I wrote...

https://github.com/paboyle/Grid/blob/develop/documentation/Grid.pdf