Dynamically update Kanister version in docs (kanisterio#327)

* Dynamically update Kanister version in docs

- This assumes that docs are generated and published after the release
- This also removes the docs package from the bump_version script

* Tweak texxt

build/bump_version.sh

@@ -27,7 +27,7 @@ usage() {
 main() {
     local prev=${1:?"$(usage)"}
     local next=${2:?"$(usage)"}
-    local -a pkgs=(docker/ scripts/ examples/ pkg/ helm/ docs/)
+    local -a pkgs=(docker/ scripts/ examples/ pkg/ helm/)
     grep -E "${prev}" -r  "${pkgs[@]}" | cut -d ':' -f 1 | uniq | xargs sed -ri "s/${prev}/${next//./\\.}/g"
 }
 

docs/conf.py

@@ -21,6 +21,9 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import re
+import subprocess
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -33,6 +36,8 @@
 extensions = ['sphinx.ext.todo',
     'sphinx.ext.ifconfig',
     'sphinx.ext.githubpages',
+    'sphinx-prompt',
+    'sphinx_substitution_extensions',
     'sphinxcontrib.spelling']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,10 +61,16 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = ''
-# The full version, including alpha/beta/rc tags.
-release = ''
+git_describe = str(subprocess.check_output(['git describe --tags --always'], shell=True).decode('utf-8')).strip()
+# Extract the short X.Y.Z version.
+version = git_describe.split('-')[0]
+# The full version, including git hash but without # commits
+release = re.sub(r'-.*-', '-', git_describe)
+
+rst_epilog = '.. |version| replace:: %s' % version
+substitutions = [
+    ('|version|', version)
+]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/functions.rst

@@ -423,7 +423,7 @@ restore the data and then scale it back up.
 For this phase, we will use the `backupInfo` Artifact provided by
 backup function.
 
-.. code-block:: yaml
+.. substitution-code-block:: yaml
   :linenos:
 
   - func: ScaleWorkload
@@ -438,7 +438,7 @@ backup function.
     args:
       namespace: "{{ .Deployment.Namespace }}"
       pod: "{{ index .Deployment.Pods 0 }}"
-      image: kanisterio/kanister-tools:0.21.0
+      image: kanisterio/kanister-tools:|version|
       backupArtifactPrefix: s3-bucket/path/artifactPrefix
       backupTag: "{{ .ArtifactsIn.backupInfo.KeyValue.backupIdentifier }}"
   - func: ScaleWorkload
@@ -498,7 +498,7 @@ args, so this function will restore data on all pods concurrently.
 For this phase, we will use the `params` Artifact provided by
 BackupDataAll function.
 
-.. code-block:: yaml
+.. substitution-code-block:: yaml
   :linenos:
 
   - func: ScaleWorkload
@@ -512,7 +512,7 @@ BackupDataAll function.
     name: RestoreFromObjectStore
     args:
       namespace: "{{ .Deployment.Namespace }}"
-      image: kanisterio/kanister-tools:0.21.0
+      image: kanisterio/kanister-tools:|version|
       backupArtifactPrefix: s3-bucket/path/artifactPrefix
       backupInfo: "{{ .ArtifactsIn.params.KeyValue.backupInfo }}"
   - func: ScaleWorkload

docs/helm.rst

@@ -24,9 +24,9 @@ local setup. To do so, please run the following command.
 
 You also need to install the Kanister controller
 
-.. code-block:: console
+.. substitution-code-block:: console
 
-   $ helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=0.21.0
+   $ helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=|version|
 
 Kanister-Enabled Applications
 =============================

docs/install.rst

@@ -29,13 +29,13 @@ Deploying via Helm
 
 This will install the Kanister controller in the `kanister` namespace
 
-.. code-block:: bash
+.. substitution-code-block:: bash
 
    # Add Kanister charts
    $ helm repo add kanister https://charts.kanister.io/
 
    # Install the Kanister operator controller using helm
-   $ helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=0.21.0
+   $ helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=|version|
 
    # Create an S3 Compliant Kanister profile using kanctl
    $ kanctl create profile s3compliant --bucket <bucket> --access-key ${AWS_ACCESS_KEY_ID} \
@@ -71,7 +71,7 @@ the namespace fields in `bundle.yaml.in` to deploy in a namespace of your
 choice. By default, the controller will be deployed into the `default`
 namespace.
 
-.. code-block:: bash
+.. substitution-code-block:: bash
 
-   # Deploy controller version 0.21.0 to Kubernetes
-   $ make deploy VERSION="0.21.0"
+   # Deploy controller version |version| to Kubernetes
+   $ make deploy VERSION="|version|"

docs/overview.rst

@@ -58,13 +58,13 @@ package manager.
 The following commands will install Kanister, Kanister-enabled MySQL
 and backup to an AWS S3 bucket.
 
-.. code-block:: bash
+.. substitution-code-block:: bash
 
   # Add Kanister Charts
   helm repo add kanister http://charts.kanister.io
 
   # Install the Kanister Controller
-  helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=0.21.0
+  helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=|version|
 
   # Install MySQL and configure its Kanister Blueprint.
   # Also create a Profile CR that can be used in ActionSets

docs/tooling.rst

@@ -369,13 +369,13 @@ The usage for these commands can be displayed using the `--help` flag:
 
 The following snippet is an example of using kando from inside a Blueprint.
 
-.. code-block:: console
+.. substitution-code-block:: console
 
   kando location push --profile '{{ .Profile }}' --path '/backup/path' -
 
   kando location delete --profile '{{ .Profile }}' --path '/backup/path'
 
-  kando output version 0.21.0
+  kando output version |version|
 
 Install the tools
 =================
@@ -395,10 +395,10 @@ Docker Image
 ============
 
 These tools, especially `kando` are meant to be invoked inside containers via
-Blueprints. Although suggest using the released image when possible, we've also
+Blueprints. Although we suggest using the released image when possible, we've also
 made it simple to add these tools to your container.
 
-The released image, `kanisterio/kanister-tools:0.21.0`, is hosted by
+The released image, `kanisterio/kanister-tools`, is hosted by
 `dockerhub <https://cloud.docker.com/swarm/kanisterio/repository/docker/kanisterio/kanister-tools/general>`_.
 
 The Dockerfile for this image is in the