Use consistent heading and class style for parser catalogue about insights-core HOT 5 CLOSED

Something a bit more similar to the current format would be:

{{ for each class in the module:}}
{{parser class name} - {{ file or command }}
------------------------------------------
.. autoclass:: insights.parsers.{{module}}.{{parser class name}}
   :members:
   :show-inheritance:
{{ endfor }}

Would that be OK @bfahr ?

from insights-core.

@bfahr in looking at this - does this mean we end up moving the file documentation out of the parser's main docstring and into the .rst file? That'd be a step backward to me - I'd like to keep as much documentation as possible in the parser module. I'll continue to experiment but any advice you have will be invaluable here :-)

from insights-core.

The key thing I want to aim for in this is that every parser module lists every parser class it provides, in a format that makes it easy for a rule writer to find the parser they need based on the file they want to read.

I'd also like consistency - i.e. that every module listing looks the same, regardless of whether it has one or six parsers in it.

I'm prepared for the .rst file to require more management as a result, but OTOH I would really like to keep the automatic functionality and single place for documentation changes that we currently have.

from insights-core.

@PaulWay I agree that we don't want have have the docs in both the code and the .rst file. The .rst file should just be the map for building the doc, and not the doc itself. Otherwise we've got a disconnect and have to maintain it in two places.

Its a bit hard to visualize, I think it might be easier to discuss if it was mocked up.

from insights-core.

Closing due to age. We can revisit with a larger conversation about style of the catalog at a future date.

from insights-core.