search

QMCPACK / qmcpack

Main repository for QMCPACK, an open-source production level many-body ab initio Quantum Monte Carlo code for computing the electronic structure of atoms, molecules, and solids with full performance portable GPU support
http://www.qmcpack.org
Other
298 stars 139 forks source link

marked up Formulas in class documentation should actual render in doxygen #4088

Open PDoakORNL opened 2 years ago

PDoakORNL commented 2 years ago

It seems like the only place a fair amount of the math used in our implementations is documented is in the actual source. But most of it does not render in our doxygen output since most of it is either bad/incomplete latex or not marked up properly.

see https://doxygen.nl/manual/formulas.html

This is important because there are often significant differences between implementation and them manual or some paper from 5-50 years ago.

Describe the solution you'd like Folks should fix these as they find they're doing work in relevant files. Do it in a small PR before or after your significant work. It will help your metrics.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

prckent commented 2 years ago

Peter - do you run doxygen locally? Are there warnings from the bad markup? How big is the problem? To move doxygen to a first class citizen in our docs we need a practical way to catch and fix up these issues. I see that there are GitHub actions for doxygen and we could switch our publishing to a GitHub page, which would simplify our infrastructure overall.

PDoakORNL commented 2 years ago

Yes I do. But doxygen knows nothing about them not rendering because they are just latex thrown into comments without the correct markup. See link above. In general everyone who is contributing significantly needs to build the doxygen once and a while and see what their docs turn out looking like. At the moment spack install doxygen seems sufficient to run ours.