Description
Package
next-drupal (NPM package)
Describe the feature request
We've updated the documentation site to generate API docs using Typedoc in order to reduce the maintenance effort for that section of the site (not to mention to force us to better document our code.) But we admittedly did lose some of the detail from the existing reference sections along the way.
Describe the solution you'd like
Ideally we'd port examples and other natural language content to the new system. Some of this should be possible with the @examples tag in typedoc. We may also find that some of the detail really isn't appropriate for the API docs, and should be moved to the main documentation.
Other things to consider:
- Moving a link to the API docs to the top level header menu.
- Determining if there is anything we should hide from the automatic API docs. Similarly, what should we do with deprecated things?
- Can any supporting content, landing pages, or menu adjustments make this more useful?
Describe alternatives you've considered
My initial pass at this was integrating the docs into the system using typedoc-markdown. This integrates well with our bespoke docs site, but loses some documentation detail in the meantime. As you'll see from a PR in a little bit, I'm now experimenting with generating the standard HTML API reference - this is better in my opinion content wise, but a jarring transition from the main docs. I currently think this is the better trade-off, but am open to discussion.
Additional context
This change will still be a trade-off. Automatically generated API docs can't (and probably shouldn't be) the same as custom authored docs. But should be able to make this better - even if the effort continues beyond the 2.x stable release.