John Snow <js...@redhat.com> writes:
> Although "deprecated" is a feature (and *will* appear in the features
> list), add a special :deprecated: option to generate an eye-catch that
> makes this information very hard to miss.
>
> (The intent is to modify qapidoc.py to add this option whenever it
> detects that the features list attached to a definition contains the
> "deprecated" entry.)
Let me explain it in my own words to make sure I understand.
1. The transmogrifier emits a :feat: for the feature like for any other.
Therefore, the feature is rendered like any other.,
2. The transmogrifier additionally emits the owning directive with a
:deprecated: option. This gets the eye-catch rendered.
Example:
Command drive-backup (Since: 1.6)
--> This command is deprecated.
Start a point-in-time copy of a block device to a new destination.
The status of ongoing drive-backup operations can be checked with
query-block-jobs where the BlockJobInfo.type field has the value
'backup'. The operation can be stopped before it has completed
using the block-job-cancel command.
Arguments:
* The members of "DriveBackup".
Features:
--> * **deprecated** -- This command is deprecated. Use "blockdev-
backup" instead.
The first arrow marks the eye-catch. The second marks the normally
rendered feature.
The eye-catch is redundant with the feature rendering. Readers may
nevertheless find an eye-catch useful.
For what it's worth, the Python documentation has deprecation
information at the end of a definition documentation, together with
"changed in" information. Both are colored to catch the eye. More
restrained than your eye-catch. Also uses less space.
Hmm.
Not a blocker.
> -
>
> RFC: Technically, this object-level option is un-needed and could be
> replaced with a standard content-level directive that e.g. qapidoc.py
> could insert at the beginning of the content block. I've done it here as
> an option to demonstrate how it would be possible to do.
>
> It's a matter of taste for "where" we feel like implementing it.
>
> One benefit of doing it this way is that we can create a single
> containing box to set CSS style options controlling the flow of multiple
> infoboxes. The other way to achieve that would be to create a directive
> that allows us to set multiple options instead, e.g.:
>
> .. qapi:infoboxes:: deprecated unstable
>
> or possibly:
>
> .. qapi:infoboxes::
> :deprecated:
> :unstable:
>
> For now, I've left these as top-level QAPI object options. "Hey, it works."
Do you intend to drop this part in the final version?
Having the commit message explain paths not taken can be useful. But
this is phrased as an RFC, which suggests to me you plan to drop it.
> P.S., I outsourced the CSS ;)
Hi, Harmonie!
> Signed-off-by: Harmonie Snow <harmo...@gmail.com>
> Signed-off-by: John Snow <js...@redhat.com>
