Interest in m.css as back end to dox++?

[crisluengo]

I got really tired of all the weird work-arounds in my documentation sources for Doxygen. And I see no solution in sight for some issues like the lack of links within documentation for one group to types documented in another group, which really bugs me.

So... I did this: https://github.com/crisluengo/doxpp

There's still a few minor things that don't work well, mostly related to template specializations and function pointers.

Still, I'm ready to build the back end to this thing, the part that takes the JSON data and outputs pretty HTML. Of course I want it to look like my current docs, which use m.css. :+1:

I was wondering, should I add this program to m.css, or should I add it to my own project and just copy over stylesheets and templates from here? What would your preference be?

[crisluengo]

An update, for when you have time to look at it.

This site is now generated by the new dox++ tool.

I have significantly modified your templates so that I needed to do less work renaming dictionary fields to match the templates, and also to accomplish a few things that couldn't be done with the Doxygen output but are trivial now, for example simple classes, structs and unions (the ones that only have member variables) are documented inline. I also had to modify the CSS a tiny bit to accommodate the different HTML generated by Python-Markdown. Here is an (incomplete) list of differences in the output with stock m.css.

The dox++ project now has a copy of your search functionality, as well as modified copies of your templates and CSS. I also took your latex2svg.py module and created a Python-Markdown plugin with it: https://github.com/crisluengo/mdx_math_svg

I hope there's sufficient attribution! :smile:

[mosra]

(Sorry for embarrassingly late replies, finally got a chance to get back to this project.)

Hey, this is great! I contemplated doing a similar thing myself, but in the end didn't because I expected it to be an even bigger time sink than working around Doxygen bugs every now and then. In my case I wanted to have a Docutils-based doc block parser so I can reuse most of the code and plugins done for the Pelican theme and Python doc generator.

Re integrating the two projects, I see a few options:

• Integrate dox++, make it mostly compatible with Doxygen docblock syntax so existing projects can switch to it, and gradually drop the Doxygen backend. From user perspective this has the best potential as ideally would be just a matter of switching the tool they build with, without having to rewrite all their docs to some new syntax. From our perspective it however requires a lot more time investment as users would request new features (recognizing and supporting features from new C++ standards, ...) and would demand bug fixes. Given that I couldn't really find much time to tackle m.css issues and PRs for the past two (!!) years, I can't imagine this being a viable option -- with Doxygen being an external project of headcount > 1, it was at least possible that some parser bugs would get fixed by someone else, and m.css itself would bet on being really tiny and well tested to survive several months without needing much attention. Similarly for you, I don't think you'd want to drop all your other projects just to be able to keep up with people demands for a C++ parser.
• Integrate dox++ next to Doxygen and maintain both side by side, giving people choice between "all features in the universe" and "no stupid annoying bugs". Since the new backend can't really share much with neither Doxygen (because the templates have to be different) nor the Python doc generator (because you don't use reST for doc blocks), it would require a lot of maintenance effort, which I don't have.
• Integrate the dox++ C++ parser but switch to reST for docblocks so I can share as much code as possible with the Python/Pelican part of m.css. This would be the best option for me as I would use that as an opportunity to switch all my code docs to a better markup format, but would mean I'd bother you a lot with implementing whatever else I would need (which, again, you may not have time for, and might not be interested in). And then there's the Doxygen backend, which a lot projects already use, so making it suddenly disappear isn't really an option yet, meaning I'll still need to maintain it as well for some time.

I ... don't know, heh. Ideal case would be to have a C++ parsing lib that's well tested, has all features needed by a doc parser and is backed by a larger community so it doesn't depend on a single person time and willingness. Your library ticks the first two boxes, vanilla clang the first and last, and doxygen the last two. There's nothing that would cover all three, yet.

So if you can keep it as a separate project and have m.css used just for the CSS and the search thingy, that's probably the best option right now. If there's anything I can do to bring the two projects closer together (say, get rid of some crazy doxygen-specific naming in my templates), let me know.

[crisluengo]

The dox++ project has modified copies of your CSS and HTML templates, which sucks because it'll be lots of work to port over your improvements. The CSS is mostly the same, and shouldn't be hard to merge the two versions. But I just don't see a way in which your templates would serve both projects at the same time, I needed to make large changes to them to get it all to work.

So, I unfortunately don't see a way to integrate the two projects at this point.

---

I expected it to be an even bigger time sink

Yes, it took a lot of time to implement, I thought it would be easier. But it was a good way for me to get more familiar with Python. :)

The disadvantage of clangd is that getting the relevant information out can be terribly hard, and some stuff is just impossible to get at all without manually parsing the code for the given declaration, so you still end up doing some manual parsing. It was a little disappointing, to be honest. Still, I'm getting more useful information in my documentation now than I was with Doxygen, so I'm happy with the results.

Integrate dox++, make it mostly compatible with Doxygen docblock syntax so existing projects can switch to it, and gradually drop the Doxygen backend.

The whole point of the dox++ project is to not be as boneheaded as Doxygen with some of its syntax. I tried to be mostly compatible, but did things differently in places on purpose. But of course it should be possible to recognize more of the Doxygen syntax, I'm just not sure if I'd have enough motivation to do so.

Integrate the dox++ C++ parser but switch to reST for docblocks so I can share as much code as possible with the Python/Pelican part of m.css.

I can see dox++ doing both reST and Markdown. There are two tools, the one that extracts data from the C++ header files inserts some Markdown links into the documentation, but otherwise is agnostic to the markup used in the documentation blocks. It could have a switch to change how links are inserted. The second tool produces the output HTML, this is the one that would need more serious work to use a reST markup engine instead of Markdown. If someone wants to put in that effort, I'm happy to help a bit, but I don't think I'd find the motivation to do that on my own, since I wouldn't have a use for it myself.