Bump docusaurus version and add support for versioning (#4506)

* Bump docusaurus version and versioning - Bump docusaurus to latest 2.0 version - Fix errors thrown up by new linting process - Add version support, setup 4.0.0 - Enable dark mode and fix in home screen * Move status_updates back into root project docs folder * Fix links - fix dead links - ensure all links are relative (so work when versioned) * Remove version 4.0.0 * WIP * WIP * Completed * Temporarily remove docsVersionDropdown until first version added to internal-versions * Update website docs * Build fix for temp situation where there's no versions * Add custom version of 'not latest released docs' message * Improve versioning and dark mode toggle - Add `All Versions page` - Conditionally include versions in drop down - Improve dark mode toggle icons * Temporarily remove dependent on versions - will be added back in when 4.0 sha is known * Update Versions Process * Add 4.0.0 * Fix in `build`/`serve` world - worked fine in `start` world... * Update 4.0.0 with temp version * Multiple improvements - Fix clean git repo before run - Swizzle docs version drop down nav bar item, move in custom code - Improve docs (latest version must appear in drop down) * Changes following review * Reduce font in version warning
cloudfoundry · Sep 3, 2020 · 3726821 · 3726821
1 parent 545669a
commit 3726821
Show file tree

Hide file tree

Showing 25 changed files with 2,342 additions and 1,916 deletions.
diff --git a/.gitignore b/.gitignore
@@ -124,3 +124,7 @@ go-vendor-*.tgz
 website/build
 website/site-dist
 website/.docusaurus
+website/versioned_docs
+website/versioned_sidebars
+website/versions.json
+website/versions-repo
diff --git a/website/README.md b/website/README.md
@@ -26,7 +26,7 @@ This command starts a local development server and open up a browser window. Mos
 $ ./deploy.sh -b
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+This command generates static content into the `build` directory and can be served using any static contents hosting service, or `npm run serve` to see locally.
 
 ### Deployment
 
@@ -37,4 +37,50 @@ $ ./deploy.sh
 ```
 
 
-> Note: The website is deployed to the GitHub Repository `cf-stratos/wesbite` which hosts https://stratos.app
+> Note: The website is deployed to the GitHub Repository `cf-stratos/wesbite` which hosts https://stratos.app
+
+### Version
+
+Versions is handled automatically by `npm run versions` which is called as part of `npm run build`. The `versions` target runs `build-versions.sh` which
+
+> The files is `docs/` will be marked as `next`.
+
+1. clones a local copy of the repo
+1. cleans up any previous run (repo aside)
+1. Loop through each version defined in `internal-versions.json` (latest version is highest)
+  - checkout that version in temp repo
+  - tag that version with it's version label using docusaurus
+  - copy the files docusaurus creates back into the main repo
+  - store the label
+1. remove the local clone
+
+#### Add a new version
+
+1. Open `internal-versions.json`
+1. Add to the top `<label of version to be displayed in website>:<version of repo to checkout that contains required docs>:<show version in versions drop down`. For example `[ "4.0.0:4.0.0:true"]`
+1. Commit, push and merge changes
+
+> Note - the most recent version (first in array) MUST be visible in the drop down. This is the version that is picked by Docusaurus as the default
+
+Everything else should be handled by the CI process (building with all versions in file and publishing)
+
+
+# Updating Docusaurus Version
+If the version of Docusaurus is updated be careful of changes to components that have been 'swizzled`. These are theme components that we have copied using the swizzle command and tweaked locally. 
+
+For example
+
+```
+npm run docusaurus -- swizzle @docusaurus/theme-classic Navbar
+```
+
+Currently these components are in `./website/src/theme`
+- DocsVersionDropdownNavbarItem (trims out versions in drop down, shows link to all versions)
+- DocVersionSuggestions (fixes text shown when not on last released version)
+- NavBar (dynamically hide the versions drop down if not in the docs section)
+
+After Docusaurus is updated these will remain the Stratos version of the old Docusaurus version. Therefore may need to be recreated using swizzle and applying the same changes.
+
+Note, there are also two non-swizzled custom pages that may also need updating. Current these components are in `./website/src/pages/*.js`
+- index.js (home page)
+- versions.js (all versions page)
diff --git a/website/build-versions.sh b/website/build-versions.sh
@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+function logInner() (
+  echo ..... $1
+)
+
+function cleanUpBefore() (
+  currentWebsite=$1
+
+  rm -rf $currentWebsite/versioned_docs
+  mkdir -p $currentWebsite/versioned_docs
+
+  rm -rf $currentWebsite/versioned_sidebars
+  mkdir -p $currentWebsite/versioned_sidebars
+
+  echo "[]" > $currentWebsite/versions.json
+
+  cleanUpGit
+) 
+
+function gitClone() (
+  rurl="$1" localdir="$2"
+  echo "Cloning from $rurl into $localdir"
+  git clone --depth 1 --no-single-branch $rurl $localdir
+  pushd $localdir/website > /dev/null
+  npm install
+  popd > /dev/null
+)
+
+function checkoutAndTag() (
+  logInner "Checking out: $versionsHash"
+  pushd $tempDirForGit > /dev/null
+  git checkout $versionsHash
+  pushd website > /dev/null
+  logInner "Tagging with version $versionsLabel"
+  npm run version -- $versionsLabel
+  popd > /dev/null
+  popd > /dev/null
+)
+
+function createVersionedDocs() (
+  logInner "Updating versioned docs folder"
+  checkedOutRepo=$1
+  currentWebsite=$2
+  label=$3
+
+  mkdir -p $currentWebsite/versioned_docs
+  cp -r $checkedOutRepo/website/versioned_docs/version-$label $currentWebsite/versioned_docs
+)
+
+function createVersiondSidebar() (
+  logInner "Updating versioned sidebar"
+  checkedOutRepo=$1
+  currentWebsite=$2
+  label=$3
+
+  mkdir -p $currentWebsite/versioned_sidebars
+  cp $checkedOutRepo/website/versioned_sidebars/version-$label-sidebars.json $currentWebsite/versioned_sidebars
+)
+
+function updateVersionsFile() (
+  vString=$1
+  if [ $vString = "]" ]; then
+    echo "No content for versions file"
+    return
+  fi
+  echo Updating versions file from $vString
+  versions="[${vString:1}"
+
+  echo to $versions
+  echo $versions > $versionsFile
+)
+
+function cleanUpGit() (
+  echo Removing folder: $tempDirForGit 
+  rm -rf $tempDirForGit
+) 
+
+
+# wesbite folder
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
+
+# tempDirForGit=$(mktemp -d)
+tempDirForGit=$DIR/versions-repo
+mkdir -p $tempDirForGit
+
+gitUrl=$(git remote get-url origin)
+versionsFile="versions.json"
+internalVersionsFile="internal-versions.json"
+
+echo ---------- Values  -------------
+# echo Hashes to treat as version: $hashes
+echo Temp Dir: $tempDirForGit. This will be removed
+echo GIT Url: $gitUrl
+echo Versions File: $versionsFile
+echo Internal Versions File: $internalVersionsFile
+echo Current Directory: $DIR
+
+cleanUpBefore $DIR
+
+gitClone $gitUrl $tempDirForGit
+
+versions="]"
+
+internalVersions=$(jq -r '.[]' $internalVersionsFile)
+export internalVersionsArray=($internalVersions)
+
+# Loop through each version 
+# .. checkout that version in the temp dir
+# .. tag that version with it's label using docusaurus
+# .. copy the files docusaurus creates back into the main repo
+# .. store the label 
+# The versions are reveresed, not so important at the moment but it's useful for future improvements
+# if the docusaurus labelling works from oldest to newest. The order in the versions.json file should
+# go from newest (first in array) to oldest (last in array)
+for ((i = ${#internalVersionsArray[@]} - 1;i >= 0;i--)); do
+  row=${internalVersionsArray[i]}
+  IFS=: read versionsLabel versionsHash includeInDropDown <<< $row
+
+  # This is donw via the website now
+  # if [ $includeInDropDown != "true" ]; then
+  #   echo Skipping version: $versionsLabel \"$includeInDropDown\"
+  #   continue
+  # fi
+
+  if [ -z "$versionsLabel" ]; then
+    echo Invalid row \(no version label\): $row 
+    exit 1
+  fi
+
+  if [ -z "$versionsHash" ]; then
+    echo Invalid row \(no version hash\): $row
+    exit 1
+  fi
+
+  echo Process version \'$versionsLabel\' with checkout target of \'$versionsHash\'
+
+  checkoutAndTag
+  createVersionedDocs $tempDirForGit/ $DIR $versionsLabel
+  createVersiondSidebar $tempDirForGit $DIR $versionsLabel
+  versions=,\"$versionsLabel\"$versions
+
+  echo Finished processing \'$versionsLabel\'
+
+done
+
+updateVersionsFile $versions
+cleanUpGit $tempDirForGit
diff --git a/website/docs/deploy/cloud-foundry/cloud-foundry.md b/website/docs/deploy/cloud-foundry/cloud-foundry.md
@@ -65,7 +65,7 @@ applications:
 
 This will set the the UAA client and UAA secret used to invite users for the default CF only.
 
-See the [invite users guide](../guides/admin/invite-user-guide) for more information about user invites in Stratos.
+See the [invite users guide](../../advanced/invite-user-guide) for more information about user invites in Stratos.
 
 #### Use of the Default Embedded SQLite Database
 
@@ -127,7 +127,7 @@ cf push console -o splatform/stratos:stable -m 128M -k 384M
 
 Alternatively cf push using a manifest
 
-- download [manifest-docker.yml](../../../manifest-docker.yml) or create your own manifest file:
+- download [manifest-docker.yml](https://raw.githubusercontent.com/cloudfoundry/stratos/master/manifest-docker.yml) or create your own manifest file:
     ```yaml
     applications:
     - name: console

diff --git a/website/docs/developer/frontend.md b/website/docs/developer/frontend.md
@@ -12,12 +12,12 @@ Before making changes to the frontend code you should be familiar with
 1. Redux / NGRX / Observables
 1. Node / NPM
 
-There are a some introduction style resources [here](/docs/developer/developers-guide-env-tech.md). There's also some advice on helpful [VS code plugins](/docs/developer/developers-guide-env-tech#vs-code-plug-ins). If you feel comfortable with these and are happy with your dev environment please skip straight to
+There are a some introduction style resources [here](./developers-guide-env-tech.md). There's also some advice on helpful [VS code plugins](./developers-guide-env-tech#vs-code-plug-ins). If you feel comfortable with these and are happy with your dev environment please skip straight to
 [Set up Dependencies](#set-up-dependencies).
 
 ## Set up Dependencies
 
-* Set up a Stratos backend. Both backend and frontend exist in this same repo. Follow the [Backend Development](/docs/developer/introduction#build--run-locally) set up guide.
+* Set up a Stratos backend. Both backend and frontend exist in this same repo. Follow the [Backend Development](./introduction#build--run-locally) set up guide.
 * Install [NodeJs](https://nodejs.org) (if not already install) (minimum node version 12.13.0)
 * Install [Angular CLI](https://cli.angular.io/) (if not already install) - `npm install -g @angular/cli`
 
@@ -55,7 +55,7 @@ We use the angular material theming mechanism. See [here](https://material.angul
 
 ### Extensions
 
-Documentation on extensions can be found [here](/docs/extensions/introduction). From a developers perspective extensions are managed by npm packages.
+Documentation on extensions can be found [here](../extensions/introduction). From a developers perspective extensions are managed by npm packages.
 The default set are in `./src/frontend/packages`, any package added directly here will be automatically included by the build.
 
 At build time the Stratos Devkit (`./src/frontend/packages/devkit`) will ensure all packages are imported correctly and theming, both component and console level, are applied correctly.

diff --git a/website/docs/developer/introduction.md b/website/docs/developer/introduction.md
@@ -32,6 +32,6 @@ This will build both the frontend and backend and run the backend in a mode wher
 
 You can open a web browser and navigate to (https://127.0.0.1:5443) and login with username `admin` and password `admin`.
 
-> To develop the frontend we recommend reading through the [frontend](/docs/developer/frontend) doc. This includes a faster way to run Stratos and see your changes.
+> To develop the frontend we recommend reading through the [frontend](./frontend) doc. This includes a faster way to run Stratos and see your changes.
 
-> Additional back end docs are available [here](/docs/developer/backend) before making any changes to the code.
+> Additional back end docs are available [here](./backend) before making any changes to the code.
diff --git a/website/docs/extensions/frontend.md b/website/docs/extensions/frontend.md
@@ -15,7 +15,7 @@ We use Decorators to annotate components to indicate that they are Stratos exten
 
 An example illustrating the various front-end extension points of Stratos is included in the folder `src/frontend/packages/example-extensions`.
 
-To run Stratos with these customizations see [here](/docs/extensions/introduction#acme).
+To run Stratos with these customizations see [here](./introduction#acme).
 
 For a walk-through of extending Stratos, see [Example: Adding a Custom Tab](#example-adding-a-custom-tab).
 
@@ -60,7 +60,7 @@ Your route should have the following metadata in the `data` field of the route:
 
 Where `<TITLE>` is the text label to show in the side navigation and `<ICON NAME>` is the icon to use.
 
-> The routing module must be, or referenced by, the core routing module as described [above](/docs/extensions/frontend#including-modules-and-routes)
+> The routing module must be, or referenced by, the core routing module as described [above](./frontend#including-modules-and-routes)
 
 An example routing module would be:
 
@@ -101,11 +101,11 @@ Tabs can be added to the following views in Stratos:
 - The Cloud Foundry Org view that shows detail for a Cloud Foundry organization
 - The Cloud Foundry Space view that shows detail for a Cloud Foundry space
 
-A step by step guide on how to create a custom tab can be found [below](/docs/extensions/frontend#example-adding-a-custom-tab).
+A step by step guide on how to create a custom tab can be found [below](./frontend#example-adding-a-custom-tab).
 
 For example:
 
-![Example Application tab extension](../../images/extensions/app-tab-example.png)
+![Example Application tab extension](/images/extensions/app-tab-example.png)
 
 The approach for all of these is the same:
 
@@ -130,14 +130,13 @@ The approach for all of these is the same:
     - < LABEL > is the text label to use for the tab
     - < LINK > is the name to use for the route (this must only contain characters permitted in URLs)
     An example is included in the file `src/frontend/packages/example-extensions/src/app-tab-extension/app-tab-extension.component.ts`.
-1. Declare the component to avoid Angular tree shaking
-   - In the same module that the component is 'declared' in add the following to `imports`
+1. Declare the component to avoid Angular tree shaking. In the same module that the component is 'declared' in add the following to `imports`
     ```
       ExtensionService.declare([
         <component name>,
       ])
     ```
-> The module referencing the component, or another referencing it, must be imported by the core module as described [above](/docs/extensions/frontend#including-modules-and-routes).
+  > The module referencing the component, or another referencing it, must be imported by the core module as described [above](./frontend#including-modules-and-routes).
 
 ### Custom Actions
 
@@ -152,7 +151,7 @@ Actions can be added to the following views in Stratos:
 
 An action is a icon button that appears at the top-right of a View. For example:
 
-![Example Application action extension](../../images/extensions/appwall-action-example.png)
+![Example Application action extension](/images/extensions/appwall-action-example.png)
 
 The approach for all of these is the same:
 
@@ -179,15 +178,14 @@ The approach for all of these is the same:
     - < LABEL > is the text label to use for the tooltip of the icon (optional)
     - < LINK > is the name to use for the route (this must only contain characters permitted in URLs)
     An example is included in the file `src/frontend/packages/example-extensions/src/app-action-extension/app-action-extension.component.ts`.
-1. Declare the component to avoid Angular tree shaking
-   - In the same module that the component is 'declared' in add the following to `imports`.
-    ```
-      ExtensionService.declare([
-        <component name>,
+1. Declare the component to avoid Angular tree shaking. In the same module that the component is 'declared' in add the following to `imports`.
+     ```
+     ExtensionService.declare([
+      <component name>,
       ])
-    ```
+     ```
 
-> The module referencing the component, or another referencing it, must be imported by the core module as described in [above](/docs/extensions/frontend#including-modules-and-routes)
+  > The module referencing the component, or another referencing it, must be imported by the core module as described in [above](./frontend#including-modules-and-routes)
 
 ### Loading Indicator
 
@@ -268,7 +266,7 @@ A customization service provides a number of smaller extension points.
 
 |Property | Description|
 |--|--|
-|hasEula| True if there's a EULA to show. When set to true the asset `/core/eula.html` must exist. For information about custom package assets see the images section [here](/docs/extensions/theming#new-images).  |
+|hasEula| True if there's a EULA to show. When set to true the asset `/core/eula.html` must exist. For information about custom package assets see the images section [here](./theming#new-images).  |
 |copyright| Text shown at the bottom of the side nav|
 |logoText| Text shown with the side nav logo|
 |aboutInfoComponent| Replace the component used in the Stratos `About` page|
@@ -456,4 +454,4 @@ export class MyExampleModule { }
 
 ### Run it
 
-You should now be able to run Stratos [locally](/docs/developer/introduction) and see this new tab on the application page for an application.
+You should now be able to run Stratos [locally](../developer/introduction#build--run-locally) and see this new tab on the application page for an application.