On Fri, Mar 7, 2025 at 5:48 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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. > Yep, you've got it. > > 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. > I am extremely happy to take patches to change the layout and formatting after we merge. I'm providing the canvas, others can paint :) > > > - > > > > 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. > Yep. You just hadn't reviewed these yet so I left the commentary in :) Now that you've seen it, it can go. > > > P.S., I outsourced the CSS ;) > > Hi, Harmonie! > > > Signed-off-by: Harmonie Snow <harmo...@gmail.com> > > Signed-off-by: John Snow <js...@redhat.com> > >
