docs icon indicating copy to clipboard operation
docs copied to clipboard

Reference generation script improvements

Open delucis opened this issue 3 years ago • 0 comments

Suggestions from @FredKSchott for ways to improve the scripts/docgen.mjs script that auto-generates the API reference from types in the Astro repo:

  • [ ] Instead of STUB, take an optional file path to your local @types/astro.ts file on disk to test against that. This would save a lot of copy-paste time.

  • [x] Adding support for a @version JSDoc tag that will automatically add an "Added in: v..." line to the generated Markdown if found. (Done in #215)

  • [ ] Adding support to auto-generate CLI flags from that same config, since every CLI flag maps to a configuration option. Right now, the cli-flags.md docs page is still manually maintained, but there's no reason that it couldn't be auto-generated from the same JSDoc (see @cli --project-root)

Since then the following ideas have also come up (copied over from #544 — thanks @Chrissdroid!):

  • [x] Convert https://docs.astro.build/ URLS to relative links (Done in #755)

  • [x] Add a CI script to run scripts/docgen.mjs on a 24 or 48h schedule and auto-update configuration-reference.md (Done in #755)

delucis avatar Mar 11 '22 00:03 delucis