Hacker News new | ask | show | jobs
by DrBazza 527 days ago
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'.
1 comments
eXpl0it3r 527 days ago
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.

link
DrBazza 527 days ago
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.

link
eXpl0it3r 527 days ago
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/

link
DrBazza 526 days ago
> 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...

link