Create a generator for installer options about foreman-documentation

[ekohl]

For dumps, you could add a html file to the installer, just like for the API docs. I am happy to work on better definitions for hammer help also. I think that's as important as the docs.

For the installer we do have --help and --full-help. For the foreman scenario we also generate man foreman-installer but don't do that for other scenarios which means it's also useless in downstream where the foreman scenario is not supported (and thus a misleading manpage). There's still so much to improve.

Consider yourself and @lzap well warned that I will push back on this stuff to the bitter end :) I want to do this properly. Autogenerated docs are not docs for these guides.

I'd be disapointed if you didn't push back on things you disagree with ;)

Btw, one reason for online browseable versions is that as a developer I often want to compare multiple versions. Right now for Satellite I basically end up reading the code because I don't have an instance at hand. I also can't link someone to docs in a discussion. That makes supporting users harder.

[melcorr]

I don't think we will be doing this, as I said to @Ewoud, we do not document file dumps.

[lzap]

Let's not close this one, things are not black or white now. We will be proposing a lot of thing you will not like for downstream, however that does not block us from creating such a content and only showing it upstream.

File dump is very generic term, we have a way of sticking a documentation sentence for each individual installer option. If you find those description too vague or short, let's focus on improving them in the puppet source code rather than not allowing them to be distributed in the documentation as an (optional) appendix.

[melcorr]

@lzap,
There is a certain standard these docs will have to uphold and the docs team conventions and standards will be the ones that are followed.
We are supposed to be focussing on opinionated docs. That was what the downstream docs had to offer.

I disagree completely with this approach and would be willing to invest time on the hammer command rather than dumping into docs.
If we proceed with this, we are going to end up with the same manuals you already have in Foreman.

[ekohl]

@melcorr I understand that dumping huge generated files is not desirable in most situations, but there may be an interesting subset of it. For example, we could extract a list of exposed plugins. Browsing reference documentation is for me, an advanced user, what I look for the most. Guides are more aimed at beginners. Once it's set up, reference documentation becomes the primary thing I look at.

Like @lzap I'd like to keep this issue open to see what are possible use cases and where they make sense.

[melcorr]

OK :)

For dumps, you could add a html file to the installer, just like for the API docs. I am happy to work on better definitions for hammer help also. I think that's as important as the docs.

If you have use cases, we can also create an advanced user guide with the subsets that illustrate the user scenarios you identify. If we isolate what is relevant and what is useful from the dump, that is even better.

Consider yourself and @lzap well warned that I will push back on this stuff to the bitter end :) I want to do this properly. Autogenerated docs are not docs for these guides.

[maximiliankolb]

conclusion: we don't want to maintain another list of foreman-installer options. It's already documented in guides/common/modules/con_applying-custom-configuration.adoc.