Add support for multiple version of the docs (#36)

Co-authored-by: Martin Mulholland <[email protected]>

Author: mmulholla

README.md

@@ -1,10 +1,10 @@
 # Devfile 2.0 website and documentation.
 
-The generated JSON Schema documentation for the Devfile 2.0 is available here: https://devfile.github.io/.
+The generated JSON Schema documentation for the Devfile 2.x is available here: https://devfile.github.io/.
 
-[Devfile 2.0 development documentation](https://github.com/devfile/docs/blob/master/docs/end-user-guide/assembly_making-a-workspace-portable-using-a-devfile.adoc)
+[Devfile 2.0 documentation](https://github.com/devfile/docs/blob/v2.0.x/docs/modules/user-guide/nav.adoc)
 
-[Devfile 1.0 to 2.0 migration documentation](https://github.com/devfile/docs/blob/master/docs/modules/user-guide/pages/migration_guide.adoc)
+[Devfile 2.1 development documentation](https://github.com/devfile/docs/blob/master/docs/modules/user-guide/nav.adoc)
 
 ## Contributing
 
@@ -20,6 +20,100 @@ These commands will generate the html documentation in folder `build/site`. Open
 Additionally, when pushing to a branch or working on a PR, the site is built by a GH action and
 made available in a ZIP file as a GH action build artifact, and can be tested locally.
 
+* Updates to the documentation for the Devfile version under development should be merged into the master branch.  
+* Updates to the documentation for previously released Devfile versions should be merged into the braach for the release version, for example v2.0.x. 
+
 # Issue tracking repo
 
 https://github.com/devfile/api with label area/documentation
+
+# Release process
+
+Each release a new git release, tag and branch will be created. The tag marks the initial release documentation 
+and the branch is used for any post release updates. Next release work then continues on the master branch. 
+To enable this the following release process must be followed:
+
+## Changes for the new release branch
+
+Set the new branch to be specific to the release version. For example, if the release version is 2.0.0:
+
+1. Prior to this process the api repo is updated to copy a final version of the schema to a directory for that version. For example:
+   `docs/modules/user-guide/attachments/jsonschemas/2.0.0/devfile.json
+1. Create the new branch for the tag: 
+   ```git fetch --all```
+   ```git checkout -b v2.0.x v2.0.0``` 
+1. Modify `docs/antora.yaml`:
+   1. Set the correct title and version.
+   1. Remove the pre-release attribute.
+   1. Set `.asciidoc .attributes .prod-ver` for the release
+   1. For example if release is 2.0.0
+      ```
+      name: devfile
+      nav: 
+        - modules/user-guide/nav.adoc
+      start_page: user-guide:index.adoc
+      title: Devfile User Guide v2.0.0
+      version: '2.0.0'
+      asciidoc:
+        attributes:
+          prod-ver: 2.0
+      ```
+1. Modify .gitignore to not ignore the doc generated from the schema for the release:
+      ```
+      docs/modules/user-guide/attachments/api-reference/next
+      docs/modules/user-guide/attachments/api-reference/stable
+      docs/modules/user-guide/examples/api-reference/next
+      docs/modules/user-guide/examples/api-reference/stable
+      ```
+1. Modify ```docs/modules/user-guide/partials/ref_api-reference.adoc``` to pull the iframe and link from the newly generated directories.
+   ```
+   [id="ref_api-reference_{context}"]
+    = API Reference
+
+    This section describes the devfile API.
+
+    ++++
+    <iframe src="./_attachments/api-reference/2.0.0/index.html" style="border:none;width: 100%;min-height:50em;height:-webkit-fill-available;"></iframe>
+    ++++
+
+    .Additional resources
+
+    * link:{attachmentsdir}/jsonschemas/2.0.0/devfile.json[Download the current JSON Schema]```
+    ```
+1. Build the docs and verify all looks good.
+1. Add the changes, commit the branch and push directly to the docs repo. (There is no merge required for this branch). 
+    
+## Changes to the master branch
+
+Now the master branch can be updated for the next release and to link the previous release docs 
+from the newly created ```v.2.0.x``` branch.
+
+1. Modify 'docs/antora.yaml' to set the correct title,version,pre-release and prod-ver. For example:
+   ```
+   asciidoc:
+      attributes:
+        prod-ver: 2.1
+   name: devfile
+   nav:
+     - modules/user-guide/nav.adoc
+   start_page: user-guide:index.adoc
+   title: Devfile User Guide 2.1.0
+   version: '2.1.0'
+   prerelease: -alpha
+   ```
+1. Modify `antora-playbook.yaml` to add content for the new release created:
+   ```
+   content:
+     sources:
+       - branches: HEAD
+         start_path: docs
+         url: ./
+       - branches: v2.0.x
+         start_path: docs
+         url: ./
+   ```
+1. Build, test, commit and merge the changes     
+   
+   
+
+    

antora-playbook.yml

@@ -12,7 +12,9 @@ asciidoc:
 content:
   sources: 
   - branches: HEAD
-    edit_url: 'https://github.com/devfile/docs/edit/master/{path}'
+    start_path: docs
+    url: ./
+  - branches: v2.0.x
     start_path: docs
     url: ./
 output:

docs/antora.yml

@@ -1,10 +1,11 @@
 ---
 asciidoc:
   attributes:
-    prod-ver: 2.0
+    prod-ver: 2.1
 name: devfile
 nav:
   - modules/user-guide/nav.adoc
 start_page: user-guide:index.adoc
-title: Devfile User Guide 2.0.0
-version: '2.0.0'
+title: Devfile User Guide 2.1.0
+version: '2.1.0'
+prerelease: -alpha

docs/modules/user-guide/partials/ref_api-reference.adoc

@@ -4,9 +4,9 @@
 This section describes the devfile API.
 
 ++++
-<iframe src="./_attachments/api-reference/2.0.0/index.html" style="border:none;width: 100%;min-height:50em;height:-webkit-fill-available;"></iframe>
+<iframe src="./_attachments/api-reference/next/index.html" style="border:none;width: 100%;min-height:50em;height:-webkit-fill-available;"></iframe>
 ++++
 
 .Additional resources
 
-* link:{attachmentsdir}/jsonschemas/2.0.0/devfile.json[Download the current JSON Schema]
+* link:{attachmentsdir}/jsonschemas/next/devfile.json[Download the current JSON Schema]

generate-api-reference.js

@@ -3,12 +3,12 @@
 const { Bootprint } = require('bootprint/index')
 const bootprintJsonSchema = require('bootprint-json-schema')
 const bootprintConfig = require('./reference-generator/config.js')
-const glob = require('glob-fs')();
 const fs = require('fs');
 
 fs.readdir('./docs/modules/user-guide/attachments/jsonschemas/', (err, files) => {
     if (err) throw err;
     files.forEach((version) => {
+        var glob = require('glob-fs')();
         var schemas = glob.readdirSync('./docs/modules/user-guide/attachments/jsonschemas/' + version + '/devfile*.json');
         if (! schemas.empty) {
             var schemaPath = schemas[0]