PIConGPU documentation generation broken

[psychocoderHPC]

The Sphinx docu of the dev branch is broken: https://picongpu.readthedocs.io/en/latest/dev/pmacc.html#particledescription

Building it local will create many warnings those maybe are the reason for the missing parts in the documentation.

[psychocoderHPC]

@ax3l If you can test it and help me it would be nice. I am currently fighting with the warnings but I am lost to understand the problem.

[psychocoderHPC]

I am currently correcting some errors, I will link my branch with the changes soon.

[psychocoderHPC]

I have not found the issue. The docu generation is broken since 0.3.0. The issue is reproducible in local builds. A newer Sphinx version is not solving the issue. I generated a html doxygen documentation to check if the class definitions are already missing in the doxygen xml tree, the doxygen html are fine and the definitions are available.

[PrometheusPi]

@psychocoderHPC Most warning are coming from not understanding our "C++ extensions" via templates. What warnings do you specifically thing are causing the breaking of the documentation?

[PrometheusPi]

By the way - great catch! :+1:

[psychocoderHPC]

What warnings do you specifically thing are causing the breaking of the documentation?

I thought first it is coming from the warnings but since the issue is shown up since the beginning it must be something deeper.

[PrometheusPi]

Thanks for the update. Do you need some help in investigating this bug?

[ax3l]

Those classes are not broken. If I remember correctly, I added them already in the hope that someone will add the missing doxygen strings to the classes that don't have them yet.

These warnings are just a gentle reminder to do so.

[ax3l]

Update: on further look these warnings are from documented but doxygen-wise ill-parsed classes

• ParticleDescription: probably some of the defaults are not included in the file or cannot quickly be parsed, such as boost classes
• ParticleBox: maybe the macros in members are unclear, ... can be excluded via defines for doxygen
• Frame: @tparam and @see notes do not match class arguments

In order to fix those, build the regular doxygen documentation and make sure these classes are parsed and documented correctly. After that, Sphinx/Breathe should be able to pick them up as usual.