search

slackapi / java-slack-sdk

Slack Developer Kit (including Bolt for Java) for any JVM language
https://slack.dev/java-slack-sdk/
MIT License
571 stars 212 forks source link

Docs: adds docusaurus site #1342

Closed lukegalbraithrussell closed 1 month ago

lukegalbraithrussell commented 1 month ago

Summary

This PR adds a Docusaurus site. Tested that it builds properly. This is all done in the same way as the other sites site.

https://github.com/user-attachments/assets/f6319792-48d9-4d5e-a6ad-b878f5f570ea

14,569 of those line changes are from package-lock.json. So it's really a +1900 change

If you've looked at the previous PRs, it's all pretty similar, with the exception of docs/version-config.yml and its use in .workflows/doc-deploy.

You'll see placeholders in markdown files for version values. For example: sdkLatestVersion. The github workflow replaces these placeholders with the values set in docs/version-config.yml. The sdkLatestVersion value is set via scripts/set_version.sh but the other values are changed directly in the file. When a value in version-config.yml is changed, the site is rebuilt automatically due to the github workflow looking for changes to /docs. I tested this all out on my personal deployed docusaurus test site.

Anyway, there are about only a few files in this PR that matter for review.

Maintenance files:

Site config files:

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

Folder and file organization

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

java-slack-sdk/
├── .github/
│   └── workflows/
│       └── deploy.yaml (deploys to site, and inserts values from version-config.yml)
├── docs/ (the good stuff. md/mdx files supported)
│   ├── index.md
│   └── guides
│       └── bolt-basics.md
├── i18n/ja-jp/ (the japanese translations)
│   ├── docusaurus-theme-classic/ (footer/navbar translations)
│   └── docusaurus-plugin-content-docs/
│       └── current/ ( file names need to exactly match **/docs/, but japanese content)
│           ├── index.md
│           └── guides
│               └── bolt-basics.md
├── static/
│   ├── css/
│   │   └── custom.css (the css for everything!)
│   ├── img/ (the pictures for the site)
│   │   ├── rory.png 
│   │   └── oslo.svg  
├── src/
│   ├── pages/ (stuff that isn't docs. This is empty for this repo!)
│   └── theme/ (only contains the 404 page)
├── version-config.yml (Where version numbers are set)
├── docusaurus.config.js (main config file. also where to set navbar/footer)
└── sidebar.js (manually set where the 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 for the English site.

The Japanese site unfortunately has to have slightly different slugs - they were at /guides/ja/page and docusaurus does /ja/guides/page. At that point, I changed it to /ja-jp/guides/pages to match the other sites. I've added redirects, but they may need to toggle the language once redirected.

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:

Testing

You can run the site locally:

npm install

npm run start

You can build and serve on your computer to swap between english and japanese:

npm run build

npm run serve

Click around! have fun!

Category

Just docs

Requirements

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you agree to those rules.

codecov[bot] commented 1 month ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 74.98%. Comparing base (9db47c3) to head (a94b9a7).

Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #1342 +/- ## ========================================= Coverage 74.98% 74.98% Complexity 4189 4189 ========================================= Files 451 451 Lines 12930 12930 Branches 1331 1331 ========================================= Hits 9696 9696 Misses 2463 2463 Partials 771 771 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

lukegalbraithrussell commented 1 month ago

@seratch Nice catch! For some reason Java highlighting isn't enabled by default in Docusaurus. I've added the syntax highlighting for both Java and Groovy

seratch commented 1 month ago

@lukegalbraithrussell Thanks for quickly resolving it!

With the latest revision, the only remaining issue I found is /image/* file access error. For example, img/bolt-middleware.png access from http://localhost:3000/java-slack-sdk/guides/bolt-basics returns not found HTML page instead of the png file. Can I ask you to identify the cause?

lukegalbraithrussell commented 1 month ago

@seratch The pictures are now working. Those shortened /img/path file paths (instead of /docs/static/img/path) only work in markdown it seems. I switched it to markdown!