From 77fe59adef21d5276edfb1a67e6e4798c894a8a6 Mon Sep 17 00:00:00 2001 From: Martin Mulholland Date: Thu, 21 Jan 2021 15:11:29 -0500 Subject: [PATCH] Add support for multiple version of the docs --- README.md | 100 +++++++++++++++++- antora-playbook.yml | 4 +- docs/antora.yml | 7 +- .../partials/ref_api-reference.adoc | 4 +- generate-api-reference.js | 2 +- 5 files changed, 107 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0bd595dc..715a8ed3 100644 --- a/README.md +++ b/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. + + ++++ + + ++++ + + .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 + + + + \ No newline at end of file diff --git a/antora-playbook.yml b/antora-playbook.yml index a15a5842..5b1e5947 100644 --- a/antora-playbook.yml +++ b/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: diff --git a/docs/antora.yml b/docs/antora.yml index f439b1ba..8ad21082 100644 --- a/docs/antora.yml +++ b/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 diff --git a/docs/modules/user-guide/partials/ref_api-reference.adoc b/docs/modules/user-guide/partials/ref_api-reference.adoc index fa901c84..c9b13826 100644 --- a/docs/modules/user-guide/partials/ref_api-reference.adoc +++ b/docs/modules/user-guide/partials/ref_api-reference.adoc @@ -4,9 +4,9 @@ This section describes the devfile API. ++++ - + ++++ .Additional resources -* link:{attachmentsdir}/jsonschemas/2.0.0/devfile.json[Download the current JSON Schema] \ No newline at end of file +* link:{attachmentsdir}/jsonschemas/next/devfile.json[Download the current JSON Schema] \ No newline at end of file diff --git a/generate-api-reference.js b/generate-api-reference.js index 66b3cbb4..0dd78e0f 100644 --- a/generate-api-reference.js +++ b/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]