<heller>
Yorlik: yes, the problem is almost never the tool
<Yorlik>
?
<heller>
regarding documentation
<Yorlik>
I think using two tools usually is more hassle than just using one tool.
<Yorlik>
Concerning tedious tasks, like writing tests or documentation I'm all for simplification and lowering the "Do it" threshold.
<heller>
sure, our integration in theory is good
<heller>
it is completely automated already
<heller>
and sphinx is nice to write documentation while doxygen is nice to create the reference sections
<heller>
this reminds me ... I need to finish my docs improvement ...
<heller>
gtg
<Yorlik>
The API docs are simply horrible. And that is aprtially to blame on using the wrong tool. OFC no one can help when people are not writing doxy comments in the sources.
<heller>
we are using doxygen for it ;)
<Yorlik>
I just realized yesterday that Doxygen is almost as good for general docs like Sphinx.
<heller>
you always have to have the text in some kind of comments, don't you?
<heller>
anyways
<Yorlik>
Sure. And when reading you want a usable search and all in one place
<Yorlik>
Is sphinx also using the call graphs and dependency graphs?
<heller>
we have tons of material in sphinx. pushing that down to doxygen isn't going to happen.
<heller>
some of the material simply doesn't belong into code, such as headers
<Yorlik>
Just saying - I believe it's more hassle on the long run.
<Yorlik>
I started converting my personal docs to Doxygen
<heller>
to some degree, I even think that having API references that are not generated from doxygen comments lead to a better documentation and code in the long run
<heller>
anyways: It's rarely the tool to blame
<Yorlik>
Sure. It was just a suggestion. I'm not going to push here. But I'm changing my own documentation.
<Yorlik>
Less complexity, less bug prone, less hassle.
<zao>
All our cloud docs are on whatever powers readthesdocs.
<Yorlik>
NVM ...
<zao>
Never felt that doxygen understood real C++, at least not in the 0x days. I rather ripgrep than try to use someone’s published doxygen. The only one usable is GLFW’s and that’s mostly because it has a lot of non-code prose and very little C source to ref
<Yorlik>
As much as we don't have a standard and widely accepted build system we like, it's the same with documentation. My only plea is to dumb it down as much as possible to lower the entry threshold as much as possible..
K-ballo has joined #ste||ar
<heller>
I think Sphinx is pretty straight forward
<heller>
And, reference API doc, is the least that's missing, IMHO
<heller>
So you install sphinx and breathe using pip, run cmake and then make/ninja whatever to generate it. Everything else is either rst or doxy comments
<Yorlik>
heller: Do you like the layout or navigation of the generated API docs?
<heller>
No
<heller>
But I wouldn't like it one bit better if doxygen generated html instead of docbook
<Yorlik>
Maybe at the current stage it would be easiest to have someone (Student with a knack for web development) make a good custom sphinx layout for the Docs with special look at the API docs.
<heller>
one sec
<heller>
pypi is down right now ...
<heller>
so I can't generate locally
daissgr_ has quit [Remote host closed the connection]
daissgr has joined #ste||ar
<Yorlik>
FFS another ICE ...
<Yorlik>
cl is tzrolling me again.
hkaiser has joined #ste||ar
<K-ballo>
hkaiser: here
<hkaiser>
K-ballo: sec
<hkaiser>
K-ballo: see pm, pls
<Yorlik>
How would you crosslink between Doxygen comments in source and out of source documentation? Can the current dual setup (sphinx + doxygen) to that easily?