Create documentation site

[duffn]

I'd like to create a documentation site for this repository. If this is not desired, please let me know and I can stop working on this. I've already begun.

Thoughts

• Use Jekyll and Just the Docs https://just-the-docs.github.io/just-the-docs/
• Translate all of the README to the docs site
• Add GitHub workflow to automatically publish the docs to GitHub pages at https://slack-ruby.github.io/slack-ruby-client (need repo owner help here to setup pages)
• I'll only directly copy the current documentation and then would plan to audit it for correctness after the migration

Questions

• There's a note in the current README how it's for HEAD and not for a particular version. This isn't currently available out of the box with Just the Docs https://github.com/just-the-docs/just-the-docs/issues/728. What to do here?
• I'm open to other themes or even other frameworks for docs, but Jekyll of course seemed the most appropriate and Just the Docs is a great theme

Currently

[dblock]

Good idea!

Ideally we would keep multiple versions of docs as you rightfully point out. You can probably build a workflow that publishes documentation into subfolders when a version tag is created. For the default version I would keep exactly that statement and publish docs every commit.

Don't have any strong opinions on themes.

[duffn]

Great.

Building docs off of head will be easy. Building for tags and subfolders may be tricky, but I'll explore it.

[duffn]

Here's a very rough first pass at what this could look like.

• Test repo: https://github.com/duffn/just-the-docs-dev/blob/main/.github/workflows/pages.yml
• Docs: https://duffn.github.io/just-the-docs-dev/

Notes:

• head would build on every push
• tags would build when pushed and add the docs to a /version/tag_name/ directory, so they can be browsed like this: https://duffn.github.io/just-the-docs-dev/version/v1.3.0/usage/web_client/examples.html
  • I chose the version prefix so we can easily not delete old versions when building here: https://github.com/duffn/just-the-docs-dev/blob/f5e6fa3b79b6bdf6abe03c1a6a9a0c225814089e/.github/workflows/pages.yml#L43
• search (I think rightfully) only happens within the current version
• versions could be manually added to a "versions" page here, a step to do when cutting a new release: https://duffn.github.io/just-the-docs-dev/usage/versions.html

Questions:

None really, but of course I'm open to feedback!

[dblock]

LGTM, PR something?

[duffn]

https://github.com/slack-ruby/slack-ruby-client/pull/450