feat: docusaurus plugin to generate component api docs

[sean-perkins]

What is the current behavior?

The auto generated API docs for slots, props, events, etc. does not work across versioned docs. Currently the generated contents are based on the latest available tag published to NPM (e.g. v6 at the present moment).

What is the new behavior?

This PR introduces a custom local docusaurus plugin to replace the node script for generating API docs. The plugins takes in the context from the docusaurus.config.js and uses it to generate contents automatically based on the versions specified and the contents of versions.json. This allows the plugin to work with the built-in mechanisms of versioning with Docusaurus.

Since this plugin automatically detects based on the version, there are certain assumptions that it has to make:

• If the version has a banner value of unreleased, it will use the @next tag from npm

Other information

This PR is in favor of: #2791

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
ionic-docs	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Mar 6, 2023 at 9:31PM (UTC)

[liamdebeasi]

Why not also read in versions.json? This would give you support for v5 and v6. From there all you'd need to look at is the "current" field to determine if you pull from latest or next. Once Ionic 7 is released this "unreleased" banner will go away and we'll need to pull from latest.

[sean-perkins]

What is the versions.json file used for? The v5 docs have the API reference markdown generated directly in the source files, so they do not use this plugin.

If we are ok with some configuration, we could have this plugin accept options that lets you specify the version and npm tag. It wouldn't be coupled to @docuaurus/plugion-content-docs and would be something we would need to adjust when we have a new major release, but would be more explicit.

e.g.:

[
  path.resolve(__dirname, 'plugins', 'docusaurus-plugin-ionic-component-api'),
  {
    versions: [
      {
          version: 'v7',
          tag: '@next'
      },
      {
         version: 'v6',
         tag: '@v6'
      }
    ]
  }
]

[liamdebeasi]

According to https://docusaurus.io/docs/versioning#overview: "The versions.json file is a list of version names, ordered from newest to oldest."

So sounds like as we add more versions of Ionic this versions.json file could be used to automatically make sure each version has the correct API info. The concern with relying on the content-docs plugin is it's not always going to have info for every single version. Right now we only populate versions so we can have the docs redirect to v6 while keeping v7 as the latest. But once we add Ionic 8, that object doesn't need to have info for v6.

[sean-perkins]

Ok I've updated the plugin again. It consumes the versions.json and uses that for generating markdown docs. It will look at the versions object specified on the docs plugin, but only the latest key to calculate the npm tag based off the banner field.

It's now generating markdown for v5, v6, and v7; while v5 is not used because those were already tracked in source control.

[liamdebeasi]

Great job!