[question] Incorporate doxygen-based in-line docs for Fluxion

[dongahn]

flux-sched has a ton of doxygen-based in-line documents designed to help developers to extend our Fluxion graph scheduler. For C++ based project (or even high level object based on like Python), this style of documentations would be more common.

As a test, I have a doxygen configuration for our fluxion resource infrastructure piece at https://github.com/flux-framework/flux-sched/blob/master/resource/doxygen/doxy_conf.txt, what would be a feasibility step we should take to see if it is possible to incorporate this into the overall readthedoc?

If I manually build the doxygen document out of it, I get something like the following.

If this test goes well, I can add a top level doxygen configuration spanning both resource and qmanager components.

I remember @trws said this would be possible with some tweak. And as I remember he (and @SteVwonder) would have other in-line docs for Python bindings.

[dongahn]

The other source of docs that can be very useful for our collaborators are two README.md files for resource-query and planner layer.

• https://github.com/flux-framework/flux-sched/blob/master/resource/utilities/README.md
• https://github.com/flux-framework/flux-sched/blob/master/resource/planner/README.md

Is there an established practice to incorporate READMEs into the doc project?

[trws]

On Sat, 25. Jul 12:30, Dong H. Ahn wrote:

flux-sched has a ton of doxygen-based in-line documents designed to help developers to extend our Fluxion graph scheduler. For C++ based project (or even high level object based on like Python), this style of documentations would be more common.

As a test, I have a doxygen configuration for our fluxion resource infrastructure piece at https://github.com/flux-framework/flux-sched/blob/master/resource/doxygen/doxy_conf.txt, what would be a feasibility step we should take to see if it is possible to incorporate this into the overall readthedoc?

Probably the best thing to do is to see how well it works locally with breathe or exhale, where exhale is an extended version of the sphinx breathe extension to incorporate doxygen stuff that makes it more native but slightly more fragile. If it works well with sphinx and breathe on its own, it should be relatively straightforward to include in a larger sphinx project.

[SteVwonder]

Note that it is possible for all of this to be done within the flux-sched repo, just like the manpages are now generated with sphinx from the flux-core repo. ReadTheDocs has sub-projects, so flux-sched can just be a subproject in RTD under the umbrella of "flux-framework". This allows for cross linking between projects while still allowing the repos to be separate and the documentation to be co-located with the code that is describes.

Is there an established practice to incorporate READMEs into the doc project?

Same thing for these. They can be a part of the flux-sched RTD subproject if we want them to also remain in the flux-sched repo. They will need to be converted to RestructuredText though.