Convert documentation to a more accessible format

[jottr]

Currently the documentation is available in a single README.
I would like to suggest to convert the documentation to a format which can be consumed by other tools, e.g. Dash or devdocs.io.
I found that publishing documentation via readthedocs.io, which uses sphinx to convert markdown files to the final documentation (tutorial), yields great results.
Sphinx-generated documentation can be consumed by Dash, and should be easily scrapable for devdocs.

On a side note, I found the API documentation too sparse, some methods are not explained in that section, but must be searched for in other sections (e.g. test.serial, test.cb, and so on).

I found it rather difficult, at times even confusing, when trying to look up a certain method.

[novemberborn]

I'm definitely in favor of moving the API documentation out of the README, into something that's better organized and more complete.

I'm not sure how great a fit these documentation websites are. We'd have to see if hosting Markdown files on GitHub is sufficient, or whether we should use devdocs / readthedocs / etc, in lieu of building an AVA website.

@avajs/core?

[sindresorhus]

I'm totally 👍 for this, just needs to be a solution with little overhead. I don't want a big build step.

[jottr]

There's a bunch of tools specific to API documentation, e.g. swagger and the likes.
I'd love to help improve the documentation.
@sindresorhus do you have any preference?

[sindresorhus]

e.g. swagger and the likes.

Seems like these are for web APIs, not libraries.

[sindresorhus]

I'm not really up to date on what people use for API docs these days, but I would prefer something where we could write it manually instead of it parsing JSDoc comments. I like the freedom of hand-crafting docs, as generated ones are always bad. Happy to hear suggestion on what we should use. My favorite would be just Markdown with some convention or meta tags that would make it parsable into other formats, like Dash.

[jamiebuilds]

Maybe all the documentation could be pulled into the docs directory in separate files and published to a very simple markdown-to-html website using GitHub Pages (with Jekyll) or Netlify (with anything).

Netlify is cool cause it will automatically run on PRs and give you a unique URL to preview the website on every change

[sindresorhus]

@jamiebuilds The docs site should show the latest version, not master, so I don't think we can use the docs directory approach, but yes, I'm all for just a simple Markdown site.

[sindresorhus]

https://docusaurus.io/ could be an option too, it's not simple though.

[jamiebuilds]

You can make it so that you manually select which version of the site to deploy with Netlify.

• Deploy with Netlify on every master build
• Turn off auto-publishing
• When releasing, publish the latest deployed version

[jamiebuilds]

Docusaurus is also really nice for allowing docs to be translated and versioned. Maybe worth the complexity

[nklayman]

What about vuepress? It supports markdown -> HTML, is open source, has a zero-config build step, and can be deployed anywhere.

[nklayman]

What about publishing under a different url every time, ie docs.ava.io/v1/, docs.ava.io/v2? You could then create a custom drop-down that would redirect to the correct page. Each url would be its own vuepress app, so search would work fine. There would need to be a way to retrieve new versions from an old page, however.

[novemberborn]

We could regenerate historical documentation on every build. Talk to the GitHub API to get releases, etc. Note that we'd start doing this once we publish the website, not for older versions that exist today.

[novemberborn]

I'd still like to see this. A lesson learned from @nklayman's attempt is that the solution shouldn't take me more than a couple of hours to evaluate & integrate, anything that requires more time than that is very likely to languish.

This is best achieved if the website code can live in a separate repository.

Furthermore:

• We want to write Markdown files
• We want to have the documentation browsable by release
• We want to include eslist-plugin-ava, @ava/babel and @ava/typescript in the website
• We want to use GitHub Actions to build the documentation
• We want the documentation to be available via https://avajs.dev
• The English-language Markdown files should stay in the relevant repositories, and require little changes
• Ideally, we can pull in translations from ava-docs