Docs: adds Docusaurus site

[lukegalbraithrussell]

Summary

This is the new Docusaurus site. Tested that it builds properly. This is all done in the same way as the Bolt-Python site.

python-slack-sdk.mov

This removes the Sphynx builds entirely and moves docs from .rst to .md. The legacy slackclient v2 docs are now in a legacy folder viewable on the same site. The docs folder is now the source files, and the build file is only created during the build process and not stored.

The generated reference docs go in in /docs/static now instead of /docs -- just like the bolt-python site.

Anyway, there are about only a few files in this PR that matter for review. If you've looked at the previous PRs, it's all pretty similar

Maintenance files:

• .scripts/docs.sh deleted
• .scripts/docs-v2.sh deleted
• .scripts/generate_api_docs.sh Changed the path where the reference docs go
• .github/dependabot.yml - added npm for site
• .github/maintainers_guide.md. I added a section linking to the docs README
• .github/pull_request_template.md. Removed script reference
• .workflows/docs-deploy.yml Deploys site on merge, tests on PR
• docs/README.md All the instructions

Site config files:

• docs/babel.config.js This file exists and that’s about it
• docs/docusaurus.config.js The main config file. Also where topbar and footer are set.
• docs/package.json The packages
• /docs/sidebar.js Sets the docs sidebar nav
• /docs/src/css/custom.css The CSS - matches homepage.

The 404 page has two files, for Docusaurus ~ reasons ~

• /docs/theme/NotFound/Content/index The words
• /docs/theme/NotFound/index The page the words go into

Folder and file organization

This shares the same structure as the other sites. At large:

docs/
├── content/ (the good stuff. md/mdx files supported)
│   ├── rtm.md
│   └── oauth.md
├── static/
│   ├── api_docs/ (generated reference docs)
│   │   └── slack_sdk/
│   │   │   └── index.html
│   ├── css/
│   │   └── custom.css (the css for everything!)
│   └── img/ (the pictures for the site)
│       ├── rory.png 
│       └── oslo.svg 
├── src/
│   └── theme (only contains the 404 page)
├── docusaurus.config.js (main config file. also where to set navbar/footer)
└── sidebar.js (manually set where the content docs are in the sidebar.)

Docs pages: slugs and links

The organization of pages is purposefully kept as similar to the current layout of pages so developers don't get jarred from both a site change and page changes. Slugs are all named matching that previous organization. URLs stay the same.

All .md files were renamed to match the title and the slug. Everything now matches up.

All markdown reference links were also updated to be up-to-date and working. If it's a link on the site, it now works. They should all be the most basic of markdown now.

Editing and managing the site

The README contains a basic docs editing guide. You don't need to worry about the site unless you're touching something inside the /docs folder.

There is a new action workflow: it does a test build on docs PRs and deploys the site on merges to main. It does so also on every release so the generated reference docs stay up-to-date

Next steps

This wouldn't be a DevRel project without some fast follows. This is what I plan on doing after all the sites are live:

• Set up action workflow to update this custom.css if the main site's custom.css is changed.
• General copy editing (I avoided this the best I could in this PR).

Testing

You can run the site locally:

npm install

npm run start

The reference docs won't work that way though. You'll need to build the site to replicate prod:

npm run build

npm run serve

Click around! have fun!

Category

• /docs-src (Documents, have you run ./scripts/docs.sh?) (I updated this template too!)

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.
• I've run python3 -m venv .venv && source .venv/bin/activate && ./scripts/run_validation.sh after making the changes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.01%. Comparing base (5a68e6a) to head (67168d6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1537      +/-   ##
==========================================
+ Coverage   84.96%   85.01%   +0.04%     
==========================================
  Files         113      113              
  Lines       12498    12498              
==========================================
+ Hits        10619    10625       +6     
+ Misses       1879     1873       -6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[seratch]

Checked on my local machine; this is AMAZING. Left a minor comment you can quickly resolve.

[WilliamBergamin]

Looks good 💯

[WilliamBergamin]

The lords work 🙏