John Snow <jsnow@redhat.com> writes:
> The intent here is to mark only certain definitions as visible in the
> end-user docs.
>
> All commands and events are inherently visible. Everything else is
> visible only if it is a member (or a branch member) of a type that is
> visible, or if it is named as a return type for a command.
>
> Notably, this excludes arg_type for commands and events, and any
> base_types specified for structures/unions. Those objects may still be
> marked visible if they are named as members from a visible type.
Why? I figure the answer is "because the transmogrifier inlines the
things excluded". Correct?
Yes. If a type is only ever used as a branch type or a base type and never named as a field type, it can be safely omitted from the rendered docs.
(If a type is not named in any fashion by and command or event or recursive structure therein, it's an internal type not used in QMP at all and can also be excluded safely.)
> This does not necessarily match the data revealed by introspection: in
> this case, we want anything that we are cross-referencing in generated
> documentation to be available to target.
I don't get the part after the colon.
What I mean to say is that anywhere in the generated documentation where we need to cross-reference a type name should be "doc visible".
This means, currently:
- All commands
- All events
- All member field types (including branch field types) of commands/events or nested fields therein (i.e. CommandA takes an arg "foo" of type "FooA" which in turn has a field "bar" of type "BarB"; CommandA, FooA and BarB are all doc visible types.)
- All return types and nested types therein; identical to the input rules above (You've expressed a desire to change this. Future work.)
- All alternate types (which are never inlined but instead are referenced. This can be changed later but it's just not how it works currently.)
but excludes:
- Arg types for events/commands
- Inherited object types
- Any data type that does not appear as a field/member type for a command/event input/output
- Array/List types: only the primitive types are documented with a section, not the List/Array container. This is in contrast to Alternates, where we do not perform a similar destructuring.
So, if you look at the WIP render on
gitlab.io, any (type) parenthetical links to a "qapi object" (Sphinx parlance: an indexable qapi domain *thingie*) that exists as its own section with a name and docs attached.
Those are the ones that are "doc visible".
This differs from introspection in that some (but not all) of the shared types get sections in the HTML output, but these are not API and not inherently stable with regards to their name(s) or factorings.
Introspection by contrast strips more of the names out than we do here.
> Some internal and built-in types may be marked visible with this
> approach, but if they do not have a documentation block, they'll be
> skipped by the generator anyway. This includes array types and built-in
> primitives which do not get their own documentation objects.
>
> This information is not yet used by qapidoc, which continues to render
> documentation exactly as it has. This information will be used by the
> new qapidoc (the "transmogrifier"), to be introduced later. The new
> generator verifies that all of the objects that should be rendered *are*
> by failing if any cross-references are missing, verifying everything is
> in place.
So... we decide "doc should be visible" here, and then the
transmogrifier decides again, and we check the two decisions match?
Not quite; in the generator, we visit only entities that *have docs*, so the true visibility check is (pseudocode):
ent.doc_visible() && ent.has_docs()
but we guarantee this does not cull anything inappropriate because any hanging reference is a warning that will cause a build failure. This should not be possible to trigger in the doc builder under normal circumstances.
I just mean to say: "I believe the algorithm in this patch is correct because the build would not tolerate a hanging reference, and the doc generator does in fact succeed."
Notably, the doc_visible algorithm may mark some built-in types as "visible", but they're still excluded from the html render because they simply have no docs to show. (The reference checker will not yelp for these built-in types.)