saner docs site versions

[giladgray]

🌐 new site layout:

blueprintjs.com/ 
    index.html - landing
    docs/
        index.html - latest docs site
        versions/
            1/, 2/, ...
                index.html - older versions

🔨 new deploy process:

# build the thing (unchanged)
yarn compile
yarn dist

# copy assets into site/ dir so it contains the entire site:
# landing, latest docs, older docs versions 
yarn site 

# push to master branch (github pages)
yarn deploy

site/ directory replaces docs-static as the only static site directory: no more git dir and a separate build dir. site/ contains the older versions (tracked in git) and yarn site (🔨 new build task) will copy the landing and docs apps into their proper places in site/ so it is ready to yarn deploy.

you can see updated links in versions menu (but they don't work on circle).

i'm going to make related PRs on 1.x and 2.x to simplify the versions/ release process
actually, PRs are not necessary! just need to update the wiki page: https://github.com/palantir/blueprint/wiki/Release-process

[giladgray]

(for the wiki page)

Bonus: Releasing a previous major version

The main branch of this repository contains latest code. Making a 1.x or 2.x release is similar to the process above (target release/1.x instead of develop), but the docs deployment part is different:

• Checkout release/#.x and yarn to re-install depenendencies
• Build fresh #.x docs with yarn clean && yarn compile && yarn dist
• Replace site/docs/versions/# on develop with the contents of packages/docs-app/dist
  • Copy packages/docs-app/dist/ outside of the repo.
  • Switch to develop, start a new branch.
  • Paste the contents of the folder you just copied into site/docs/versions/#. Replace all existing contents of the folder (there may be old files with md5-hashed names that are now dead code).
  • 🌟 If you maintain multiple clones of Blueprint (say at 1.x and 3.x) then this is very easy:

    rsync --recursive --delete packages/docs-app/dist/ ../blueprint/site/docs/versions/1
    

  • ⚠️ Do not run yarn site before committing as it will clean the site/ directory.
• Make a PR against develop with the changes to the static assets you just made.

[blueprint-bot]

fix gitignore to actually track docs/site/versions

Preview: documentation | landing | table

[themadcreator]

I like the new structure except two points:

1. I feel like the git clean can be a foot cannon unless you know what you're doing. This is mitigated by the fact that this is only relevant on major releases.
2. Releasing a new major version of docs requires a bit of careful thought and domain knowledge. This is mitigated by the release guide on the wiki