docs icon indicating copy to clipboard operation
docs copied to clipboard

feat: add a `<Meta />` component to document APIs

Open ArmandPhilippot opened this issue 1 year ago • 3 comments

This PR implements #9498. Feel free to check out this discussion for more context and some implementation details.

Description (required)

Changes
  • Adds a <Meta /> component to ease the authoring of the Type:/Default:/Since block
  • Updates English documentation to use the new component
  • Converts all Signature: to Type: in dev-toolbar-app-reference.mdx to be consistent (and to be able to use the component)
  • Updates docgen script to use our new component
Supported Syntaxes

<Meta /> can be used:

  • without children if there is no type (e.g. <Meta version="5.0.0" />)
  • on one line (e.g. <Meta>`number`</Meta>) or adding line breaks (after <Meta> and before </Meta>) to make it easier to read/write when the type is long
  • with HTML tags inside to use links

The available props are:

  • availableFor (to support integrations-guide/vercel.mdx)
  • cli
  • default
  • pkg and version (both are related to Since, without version the pkg do nothing)

Both cli and default properties can have backticks (Markdown syntax) to use inline code (e.g. <Meta default="`10`">`number`</Meta>) so more complicated values like <Meta default='`"development"` when running `astro dev`, `"production"` when running `astro build`'> are also supported.

Not supported
  1. Multiple types like getEntry()

We could, but the rendering on smartphone is not great... You can see some previews of my tests in the discussion.

  1. The syntax used in Collection Entry Type

Available for: is already supported by the component. The problem is the different variants for the type (Example type:/ Example Types:/Type: and which is sometimes on multiple lines). Should we add a new prop exampleType? Even if we do this, there remains the problem of multiple examples/types.

Future
  1. We let active contributors update the documentation in their language to avoid errors
  2. For languages ​​with fewer contributors, we can create a language-by-language PR with i18nIgnore
  3. Once the documentation is updated in all languages, we can remove <Since /> component OR update its syntax to use dt/dd and remove the duplicated logic from <Meta />

Related issues & labels (optional)

  • Closes #9498
  • Suggested label: consistency/formatting and feedback-improvement

ArmandPhilippot avatar Sep 30 '24 13:09 ArmandPhilippot