New Documentation

[gossi]

As I "deactivated" ec-addon-docs in #620 - I've looked into alternatives. Solutions available in ember-space are:

• guidemaker/field-guide
• docfy

Solutions "outside" embers are plenty, such as docusaurus. From the mentioned solutions I've worked with docfy and docusaurus. For this case, I can definitely vote against a solution outside ember. From the remaining I can say docfy is now-that-I-did-that-once great to do, I have no hands-on-experience with empress suite. Both are fine working with markdown files. Carrying over existing documentation will work, examples need to be transformed to the choosen-style.

I personally have done one project in docfy and would do that again for this project. I've used it in combination with picocss and had great results.

Here is the plan to implement this:

• 1. PR: Setup monorepo [1]
• 2. PR: Setup docfy
• 3. PRs: Update docs
  • Rewrite docs/ markdown files with v5 API and add a support matrix to README #721
  • Add public API docs Add API Reference section to docs site #740
• 4. Deploy new docsite (without overwriting legacy site)

[1]: Best practices for docfy is to have this in a monorepo and use one dedicated project for the docs, not to couple it to the tests. Second good point is to use it to prep for addons in v2 format (which look good in monorepo, too).

Automatic Docs Generation

I've looked into automatic documentation generators. So far I've found nothing useful, ie. using api-extractor that would automatically "connect"/be integrated into doc tools isn't there yet. Also api-extractor is questionable to play with exports field in package.json that addon v2 are using. TS team is more on the side of one export per package. There is glimmer-docgen-typescript, but would only document components and leave out a couple of important things for this addon.
Given the API surface of this plugin is luckily quite small, writing this manually with a practial and applicable examples in mind seems the best to do and likely the fastest as well (anyway time is spend in setting up an automation that will take more time than doing it manually).

Even then, as docfy can read markdown files and api-extractor/api-documentor are able to produce them is still able to look for combination in the future.

WDYT ?

[gilest]

For this case, I can definitely vote against a solution outside ember.

Yes, I think the most ember-integrated solution that is likely to be chosen by the community and maintained for a long time would be ideal.

Automatic Docs

It's a shame (although the generator for ec-addon-docs had its own problems and workarounds) but I suppose we can migrate the in-code docs to the docsite. Certainly we'll have to be more careful to enforce that code changes include updates to the docs.

Monorepo, dummy app separation, v2

Yes, I've been hoping to separate the docsite as the migration to v4 and embroider was quite painful and gave a lot of false negative in the test suite (For example the docsite and deps does not build under v4/embroider but the addon itself is actually compatible).

[gilest]

Thanks for your help with this @gossi