[meta] Supported Directives

[Mpdreamz]

This meta issue tracks our feature completeness as measured against Myst Reference on directives

myst

• admonition directive #3
• aside directive #4
• bibliography directive #5
• blockquote directive #6
• code directive #7
• code-cell directive #8
• csv-table directive #9
• dropdown directive #10
• embed directive #11
• figure directive #12
• glossary directive #13
• iframe directive #14
• image directive #15
• include directive #16
• list-table directive #17
• mdast directive #18
• math directive #19
• mermaid directive #20
• myst directive #22
• table directive #23
• topic directive  #24
• card directive  #25
• grid directive #26
• tabset directive  #27
• tab-item directive #28
• prf directive  #29
• exercise directive #30
• solution directive  #31
• margin directive #37

sphinx

As well as several directives we support from Sphinx: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

• toctree directive #32
• versionadded directive #33
• versionchanged directive  #34
• deprecated directive  #35
• versionremoved directive #36

[bmorelli25]

@KOTungseth took an initial stab at this. Here's the result of our conversation.

Not needed

• bibliography directive #5
• blockquote directive #6
• csv-table directive #9 -- focus on only one format for creating tables
• iframe directive #14
• list-table directive #17
• mermaid directive #20
• myst directive #22 -- what is this?
• topic directive  #24 -- accomplished with admonitions
• card directive  #25
• grid directive #26
• exercise directive #30
• solution directive  #31
• toctree directive #32 -- moving away from this to YAML

Not needed for 9.0

• aside directive #4
• code-cell directive #8

Needed for 9.0

Note: We still need to scope out arguments and implementation details for these issues.

• code directive #7
• admonition directive #3
  • We want to be prescriptive about the aliases we allow. The current list of 10+ is too many.
  • Note, Warning, Important, and Tip
  • This also needs to be added to the style guide
• image directive #15
• table directive #23
  • a lot of previous discussions on table capabilities to be revisited
  • do we actually need complex capabilities?
  • could go simple for v9 and more complex after?
• dropdown directive #10
• glossary directive #13
• tabset directive  #27 + tab-item directive #28
  • Note for @KOTungseth: We need to make sure this meets SEO standards
• versionadded directive #33, versionchanged directive  #34, deprecated directive  #35, versionremoved directive #36
  • Need to discuss more. We need something like this, but is this the right approach?
  • What about badges?
• Definition lists. No open issue for this functionality yet.
  • Context: docsmobile/issues/413

Further discussion required

• embed directive #11 vs include directive #16
• math directive #19 vs prf directive  #29: requires further discussion with @lcawl about ML implications
• Linking: this could be handled either with a directive or with substitution. Pros and Cons to either approach

[Mpdreamz]

mermaid, card, grid, aside are already implemented so will leave them in for now @KOTungseth @bmorelli25 under the assumption they were left out for implementation time sake?

[bmorelli25]

I'm going to close this meta issue as our initial directive support has been added. We'll look at any future support on a case-by-case basis.