gilest
commented
2 years ago 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).
As I "deactivated"
ec-addon-docsin #620 - I've looked into alternatives. Solutions available in ember-space are: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
docfyis 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]: 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
exportsfield inpackage.jsonthat 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 ?