Document addon suits/monorepos with independent versions

This discussion emerged in slack and I will try to put everything together in this issue:

Background

Open sources projects as well as companies internal projects are sometimes put together as a monorepo, i.e. to group all addons they maintain under one umbrella. These individual addons may be published either individually (= independent) or in one batch (= each addon is at the same version, an example for this is ember-decorators). In order to use ember-cli-addon-docs with those setups isn't as simple as it should be. So I'll outline what are the workarounds today and then bring in some ideas for future solutions.

Workaround 1: Multi-Documentation Multi-Version (monorepo)

In that case, each addon will have it's own ember-cli-addon-docs. Each docs will only document it's own addon, completely independent of each other.

Pros

✅ Documentation sticks to the addon

Cons

⚠️ Cannot be versioned as it is using the git tag (there is only one tag for the repo not for each addon inside)
⚠️ Cannot be put up as github page (as there is only one allowed per repo). Must be put in a subdiretory to mimic monorepo (= additional setup)

Workaround 2: Mono-Documentation Mono-Version (monorepo)

In that scenario an umbrella addon exists (like forember-decorators) that has all the other addons as dependencies and provides the documentation to them. All addons share the same version.

Pros

✅ Works out of the box
✅ Versioned docs behave adequate to the published versions
✅ Is good to document things like addon suites

Cons

⚠️ No distinction on the docs between different addons, they are represented as ONE (makes sense for projects like ember-decorators).

Workaround 3: Mono-Documentation Multi-Version (monorepo)

The umbrella addon depends on all other addons. Documentation is built in one place.

Pros

✅ Documentation is in one place
✅ Is good to document things like addon suites
✅ Navigation for projects is up to the author

Cons

❗️ Documentation is in one place
❗️ Navigation has no convention yet, is up to the author
⚠️ Requires some broccoli work to "load" dependent addons as projects, see sandbox example (= additional setup)
🚫 CONFLICTS with versioning (git tag-wise)

Workaround 4: Multi-Documentation Multi-Version (monorepo)

Each addon has it's own documentation and it's own versioning (indepdent of others).

Pros

✅ One documentation for One addon

Cons

☹️ Documentation of suites is cluttered and spread across different sites
⚠️ Cannot be put up as github page (as there is only one allowed per repo). Must be put in a subdiretory to mimic monorepo (= additional setup)
🚫 CONFLICTS with version (git tag-wise)

Workaround 5: Multi-Documentation Multi-Version (multirepo)

Each addon is its own repo, has its own documentation and its own versioning. This looks like the most viable solution as of today.

Pros

✅ Works today
✅ Versions do work
✅ Works with github pages

Cons

☹️ Documentation of suites is cluttered

Solution

Ok, let's talk about a paradise situation that I am imagining in the following lines (I might just be 1.60m short but tall enough to think big 😁):

I do see emberobserver rewritten as engine and be put up on the ember website (see this sketch and my tweet 😉).
Instead of/alternative to putting up documentation on github pages, provide a hosting service for documentation, similarly to what esdoc is doing: https://doc.esdoc.org/
Integrate emberobserver with these documentations
win. win. win.
Time to celebrate 🌴 🏖

This would mean, there is one documentation for one addon. Drop the idea of documenting suites, although it is one thing a developer can be very proud of to show everything in one place which gives some sort of portfolio.

In the meantime, emberobserver can scan package.json for the dependency of ember-cli-addon-docs, the keyword ember-addon and homepage field, create an index and provide seach for docs upon that (or mark documentation on each addon page). Something like that (I don't even know what EO is capable of as of today 🙈).

This is a great breakdown, thanks for adding this @gossi!

I definitely think we want to support multi-package repos as we go forward. There are many cases where it can lower support costs to put a few packages together (my experience with ember-decorators has convinced me of this) and as you pointed out, currently there is no standard path and there is a fair amount of custom setup.

We need to answer two questions here:

Can we support multi-addon docs in a single ec-addon-docs site in a generic, zero-config way? This is mainly a design question. Is there some way we can add navigation for a set of related addons in a single site? Keeping in mind that there can theoretically be any number of addons in a repo, though we could decide to have an arbitrary maximum number.
Can we support multiple sites in a single repo? Can we make it simple enough to setup multiple docs sites and have a single, centralized site be responsible for indexing them and loading their builds? The builds can still live in a branch on Github and be served using gh-pages, the central site would mainly be discoverability and navigation.

I think ideally we would support both of these use cases, addons can choose to coalesce documentation into a single site (especially for cases like ember-decorators where each package is very minimal) and they can choose to live in any repo configuration that makes sense, independent of package structure.

ember-learn / ember-cli-addon-docs