search

purpleidea / mgmt

Next generation distributed, event-driven, parallel config management!
https://purpleidea.com/tags/mgmtconfig/
GNU General Public License v3.0
3.67k stars 315 forks source link

Documentation generation for functions/resources #760

Open purpleidea opened 6 months ago

purpleidea commented 6 months ago

Problem:

Our end users will likely want to get information on the available resources, functions, and constants. Let's make the documentation story better.

Issues:

It is possible to get information about the resources from reading the godoc page, but it is not in the ideal format for non-golang programmers to review. We'd also like to get information about the functions and constants. That information can be queried from an internal API. (We will add a .D (documentation) sub-field for that.)

We'd like to combine all of this information into simple, clear documentation which we can push to a statically generated website somewhere (html/markdown/text?) or even output in the terminal.

Architecture:

You should write a command to mgmt (maybe mgmt doc) that provides some mechanisms/flags to generate this documentation.

If you have questions please ask here!

purpleidea commented 6 months ago

@laurent-indermuehle I believe you suggested https://abhinav.github.io/doc2go/ might be a good API to look into instead of looking at the godoc code itself. At least for parsing resources, we'd need to use one of the existing golang libraries. I expect we wouldn't be able to use either godoc or the above tool via their CLI interfaces, but we'd want to wrap their actual codebase directly. HTH