DoxyPress – Modern Doxygen | Hacker News Reader

DoxyPress – Modern Doxygen

copperspice.com

33 pointsjcbhmr11 comments

Also of note:

> What is CopperSpice

> CopperSpice is a C++ library derived from the Qt framework. Our motivation for developing CopperSpice was to change the core design of the libraries leveraging modern C++ functionality.

> The redesign allowed us to completely remove the Meta-Object Compiler (moc) system. Moc is a code generator and did not support many aspects of modern C++ including templates, complex data types, static type checking, and relied heavily on string comparisons. Removing moc improves run time performance, reduces the complexity of the build process, and allows more issues to be detected at compile time.

This sounds pretty great. Does anyone have experience using it?

This was also more interesting to me than the DoxyPress announcement.

You can use Verdigris to achieve the same with Qt https://github.com/woboq/verdigris

Any reason to not upstream the refactorings?

The default theme doesn't look that great on mobile. At least one can change the side menu size.

The challenges I'm facing with doxygen is to create a seamless integration with a MkDocs site, but not just for a single version. The current workaround of manually copying the generated MkDocs header and footer isn't very automated...

I'm also curious why it's a fork (I'm sure there's a good reason?)

Coincidentally I was looking into C++ documentation generators again.

In terms of integration, what I've settled on for apache/arrow-adbc is using Sphinx as the toplevel site generator, then writing a script that generates fake Intersphinx indices for a Doxygen site. That way you can link to Doxygen items from within Sphinx without having to hardcode URLs, instead by referencing a class name or similar, and Sphinx will warn if you reference something nonexistent, without having to use something like breathe that tries to render the Doxygen output within Sphinx. (Same approach with Javadoc -> Sphinx, too.)

It's easy enough to just use `mkdocs` with `mkdoxy` and the material theme, and you're done. In my repos it's simple enough to just run `just docs` at the root and that's it. Docs built for the given branch/tag/sha, and if various variables are set, docs deployed as well.

C++ documentation is another defect in the language (along with a build system), that all successor/modern/post C++ languages happily accept is part of the 'language ecosystem'.

Maybe I have to give mkdoxy another try. When you say "just docs", what do you mean exactly?

The thing is, if I have say 20 different versions I want to generate docs for, I don't exactly want to run this every time I run `mkdocs build`, but only if I say update the navigation.

Edit: Ah now I remember, the generated "native" Markdown structure also feels worse compared to the doxygen navigation.

I use `just` - https://github.com/casey/just and have a `docs` task. That runs a bash script that does all the heavy lifting (python install, and so on).

Though given all the chatter on here in the last couple of weeks, I'd migrate some of the python work to `uvx` and that would make things simpler again.

I'm don't know if doxygen easily supports 'incremental' builds for your use case. I've never really found completely re-building docs for my modest repos a bottleneck.

Oh, I haven't heard of `just` before. Looks interesting, thank you!

I might give mkdoxy another try, but I much prefer a solution that seamlessly integrates the doxygen docs like I'd done manually now [1]. Trying my luck here, but you wouldn't know of any extension that more easily integrates plain HTML pages into an mkdocs navigation/page?

[1] https://www.sfml-dev.org/documentation/3.0.0/

> Trying my luck here, but you wouldn't know of any extension that more easily integrates plain HTML pages into an mkdocs navigation/page?

I think you just want to use the `nav` section in `mkdocs.yml` to add non-Doxygen pages:

https://www.mkdocs.org/user-guide/configuration/#documentati...

> Supports C, C++, C#, Fortran, Java, (Corba and Microsoft) IDL, Objective-C, Python, PHP, TCL

Wondering how Python support stacks up against Sphinx. Would be nice to have a single unified tool.

Reply on news.ycombinator.com