Proposed publishing process for Docusaurus 2

[317brian]

(This PR would be merged after the Docusaurus2 upgrade in apache/druid and apache/druid-website-src)

This PR is meant purely to get feedback on the publishing process and the files listed under relevant files are the only ones that matter for that purpose. The conflicts will be resolved in the upgrade PR that will be opened.

The Druid branch that this can be tested against is this one in my fork: 317brian/druid@26-docusaurus-test-branch

It is the 26 release with 4 additional commits:

• changing the sidebar into the docusaurus2 format
• changing the redirects to the docusaurus2 format
• fixing markdown syntax so that the site can be built
• changing the img tags to use markdown syntax

The relevant files are:

• README that describes the publishing steps
• build_docs.py that builds the site
• copy_druid_docs.py that copies the Druid
• do_all_things.py that's a wrapper for build_docs and copy_druid_docs

To test this, clone my Druid fork and checkout the branch as a peer of this repo and use the instructions in the README

There are more files changed than those listed under relevant files because this also upgrades to docusaurus2 so that it can be tested (which is why the upgrade PR that will be opened needs to be merged first)

Thanks @vtlim, @ektravel , @demo-kratia, and @techdocsmith for helping get this together and testing it.

(This PR will be closed eventually and the relevant files listed above moved into the main PR for docusaurus2 to keep things neat)

[317brian]

@vogievetsky can you take a look at this and provide feedback on whether or not it works for you since you're the main site publisher.

[amaechler]

One thing that stands out to me is the Python scripts here. Since we're already in Node world with Docusaurus and all, it would feel natural to me to have node scripts instead. That would likely also integrate much nicer with the package scripts.

[317brian]

Thanks for taking a look, Andy! They're Python scripts mostly cause that's what @vtlim and I are most comfortable with. We don't have a strong attachment to them if anyone wants to redo them in a different language.

[amaechler]

Cool! I thought that might be the case, which makes sense; maybe @jgoz or myself will find some time. If not, we could always update this later on.

[317brian]

One issue I've found with this process is the "Edit this page" button on the doc pages. Because this is built in the intermediate repo using the latest or the version doc directory, the edit URL is incorrect:

https://github.com/apache/druid/edit/master/docs/latest/design/index.md

It doesn't look like there is an easy way to change it to not include latest, since this is the config:

"editUrl": "https://github.com/apache/druid/edit/master/",

So I guess the question is which trade off do we want to make:

• Continue building the site three times, ie build latest and the version in druid and copy the HTML files to druid-website-src/docs/latest and /docs/version and preserve the edit button functionality
• Turn off the Edit this page button and build twice (latest and version) in the druid-website-src repo.

[techdocsmith]

@317brian @vogievetsky , I'd like to suggest that we remove the "Edit button" at this point.

• Not many folks use it at present
• It gives the incorrect impression that you are editing the live website, which, in reality, has to be rebuild after the edit is merged.
• We can adjust the template to add a link to the docs contribution page if it would help folks make changes.

[317brian]

Closing this PR and manually porting the relevant changes to #394