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]

If you want, I'd be happy to convert the docs into separate pages for each h2 using vuepress and submit a PR.

[novemberborn]

I think as a start I'd like to split the docs across multiple Markdown files in this repository. I'd prefer to do that myself though, I can be a little particular when it comes to this kind of work 😄

[novemberborn]

We've now split the docs into multiple files: https://github.com/avajs/ava/tree/master/docs

I'd like to keep the documentation in this repository, but then publish when master is built. Then we should also have a way to browse docs for multiple versions. Also, preferably, a free or low-cost option.

[nklayman]

I converted docs to vuepress in my fork. just run npm run docs:dev to start dev server (w/ hot reload). I still need to configure the deploy command to handle versioning (and actually deploy somewhere). I assume you want to use github pages? I wanted to make sure you liked the look/style before setting up the deploy pipeline. There are also a few locations where I'm not sure what to write (home and recipes index).

[novemberborn]

Hey @nklayman, that looks nice! Apologies for waiting this long to get back to you, been a bit busy moving to another country 😄

I'm concerned about the lack of versioning support (https://github.com/vuejs/vuepress/issues/1018). I've seen a lot of confusion when it's unclear what version of the documentation you're reading, and ideally we can display documentation for previous versions. What do you reckon?

We could host this on GitHub Pages, sure. I ported my site to https://zeit.co/now the other day and that may also work quite nicely.

[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.

[jamestalmage]

I'm +1 for zeit/now. We'll get documentation builds integrated into every commit / PR / etc for free.

Implementing a drop down that lets you choose which release you're looking at will be pretty easy via Now and GH APIs

[nklayman]

Does anyone know how to get just the release tag? https://api.github.com/repos/avajs/ava/releases gives you a lot of unnecessary info.

[novemberborn]

@nklayman did you try the GraphQL API? https://developer.github.com/v4/

[nklayman]

How should I authenticate with the API?

[nklayman]

Since the graphql api forces use of an authentication token, maybe we should just host a json file with the release data ourselves, as part of the docs site.

[novemberborn]

Ideally everything is automated. Releasing is enough of a process as it is.

For now you could use a personal API token. We can swap those out with mine when the time comes.

[nklayman]

Then your access key would be publicly available on the site. I can use a postversion script to automate updating the json file, so it won't be an issue.

[nklayman]

Updated my fork to support versioning. It requests the releases.json, located in the public folder. It creates a dropdown called "versions" and links each version. The link redirects to /${version}. I also added a "version" script which adds the latest release to the releases.json. All that's left is to publish each version of the docs to /${version}.

[novemberborn]

Updated my fork to support versioning.

Would you mind opening a PR?

[nklayman]

https://github.com/avajs/ava/pull/2051

[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