From 7043f68ab78242cc28c9e3ba88af750eb50a9da1 Mon Sep 17 00:00:00 2001 From: Nicko Guyer Date: Mon, 23 May 2022 16:03:29 -0400 Subject: [PATCH 1/2] Add version support to docs site Signed-off-by: Nicko Guyer --- .github/workflows/docs.yml | 86 +++++++++++++++++++++++++++++--- docs/_config.yml | 4 -- docs/_includes/head.html | 2 + docs/_layouts/default.html | 12 +++++ docs/assets/js/versions.js | 20 ++++++++ docs/assets/js/versions.json | 3 ++ docs/tutorials/query_messages.md | 2 +- 7 files changed, 118 insertions(+), 11 deletions(-) create mode 100644 docs/assets/js/versions.js create mode 100644 docs/assets/js/versions.json diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 16bc51c79..5062a1257 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,7 +5,8 @@ on: branches: - main pull_request: - + release: + types: [released] jobs: build: runs-on: ubuntu-latest @@ -14,9 +15,18 @@ jobs: concurrency: group: ${{ github.workflow }}-${{ github.ref }} steps: - - uses: actions/checkout@v3 + - name: Checkout the current commit + uses: actions/checkout@v3 with: fetch-depth: 0 + + # If this is a new release, get the previous versions of the docs to build the full list of versions + - name: Checkout the gh-pages branch + if: github.event_name == 'release' + uses: actions/checkout@v3 + with: + ref: gh-pages + path: gh-pages - name: Setup Ruby uses: ruby/setup-ruby@v1 @@ -26,13 +36,77 @@ jobs: - name: Install bundler run: gem install bundler:1.17.2 - - name: Build doc site - run: make docs + # If this was a merge to main, set the version to "head" + - name: Set version env var to 'head' + if: github.event_name == 'push' + run: echo "DOCS_VERSION=head" >> $GITHUB_ENV + + # If this was a release, set the version number + - name: Set version env var + if: github.event_name == 'release' + run: echo "DOCS_VERSION=${GITHUB_REF##*/}" >> $GITHUB_ENV + + - name: Set version in _config.yml + run: | + echo "version: ${{ env.DOCS_VERSION }}" >> ./docs/_config.yml + + # Only need to build the full list of versions every time there is a new release + - name: Update version.json list + if: github.event_name == 'release' + run: ls ./gh-pages | grep -E '^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/.$//' | sed 's/^/[/;s/$/]/' | jq '. += ["${{ env.DOCS_VERSION }}"] | sort_by(.) | reverse | . += ["latest", "head"]' > ./docs/assets/js/versions.json + + - name: Install dependencies + working-directory: docs + run: bundle install + + - name: Build doc site version + working-directory: docs + run: bundle exec jekyll build --baseurl /firefly/${{ env.DOCS_VERSION }} + + - name: Check the docs for broken links (root) + if: github.event_name == 'pull_request' + working-directory: docs + run: bundle exec htmlproofer --allow-hash-href --assume-extension ./_site --url-swap '^/firefly/:/' --url-ignore /127.0.0.1/,/localhost/ + + - name: Check the docs for broken links (version) + if: github.event_name != 'pull_request' + working-directory: docs + run: bundle exec htmlproofer --allow-hash-href --assume-extension ./_site --url-swap '^/firefly/${{ env.DOCS_VERSION }}/:/' --url-ignore /127.0.0.1/,/localhost/ - - name: Deploy + - name: Deploy docs (version) if: github.event_name == 'push' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_branch: gh-pages - publish_dir: ./docs/_site \ No newline at end of file + publish_dir: ./docs/_site + destination_dir: ./${{ env.DOCS_VERSION }} + + ## FINAL STEPS TO COMPLETE IF THIS WAS A NEW RELEASE ## + + - name: Copy new version into version directory + if: github.event_name == 'release' + working-directory: docs + run: mv _site ${{ env.DOCS_VERSION }} + + - name: Copy existing versions into working directory + if: github.event_name == 'release' + run: ls ./gh-pages | grep -E '^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' | xargs -I '{}' mv './gh-pages/{}' ./docs + + - name: Copy existing 'head' directory into working directory + if: github.event_name == 'release' + run: mv ./gh-pages/head ./docs + + - name: Build doc site (latest) + if: github.event_name == 'release' + working-directory: docs + run: bundle exec jekyll build --baseurl /firefly + + - name: Deploy docs (latest) + if: github.event_name == 'release' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages + publish_dir: ./docs/_site + diff --git a/docs/_config.yml b/docs/_config.yml index a5241be19..02cdd13af 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -9,10 +9,6 @@ aux_links: - "https://wiki.hyperledger.org/display/FIR" "Discord": - "https://discord.gg/hyperledger" - "Mailing List": - - "https://lists.hyperledger.org/g/firefly" - "Calendar": - - "https://lists.hyperledger.org/g/firefly/calendar" color_scheme: firefly plugins: - jekyll-multiple-languages-plugin diff --git a/docs/_includes/head.html b/docs/_includes/head.html index b0332195e..df7ed4b9d 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -31,6 +31,8 @@ {% endif %} + + {% seo %} diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 34103d99b..5da3bcebc 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -117,6 +117,15 @@ +
  • + + + Version: {{ site.version | default: "latest" }} + +
    +
    +     +
    • {% endif %} @@ -222,5 +231,8 @@

    Table of contents

    {% endif %} + diff --git a/docs/assets/js/versions.js b/docs/assets/js/versions.js new file mode 100644 index 000000000..70658801a --- /dev/null +++ b/docs/assets/js/versions.js @@ -0,0 +1,20 @@ +async function getVersions(lang) { + response = await fetch('/firefly/assets/js/versions.json'); + versions = await response.json(); + + versionDropdown = document.getElementById('versionDropdown'); + + versions.forEach(version => { + versionLink = document.createElement('a'); + url = '/firefly/'; + if (version != 'latest') { + url += version + '/' ; + } + if (lang != null && lang != '' && lang != 'en') { + url += lang + '/'; + } + versionLink.href = url; + versionLink.innerText = version; + versionDropdown.appendChild(versionLink) + }); +} \ No newline at end of file diff --git a/docs/assets/js/versions.json b/docs/assets/js/versions.json new file mode 100644 index 000000000..c24f3d37c --- /dev/null +++ b/docs/assets/js/versions.json @@ -0,0 +1,3 @@ +[ + "latest" +] diff --git a/docs/tutorials/query_messages.md b/docs/tutorials/query_messages.md index bf87c715b..2f5c3ef81 100644 --- a/docs/tutorials/query_messages.md +++ b/docs/tutorials/query_messages.md @@ -28,7 +28,7 @@ This builds on the APIs to query and filter messages, described below ## Additional info -- Reference: [API Query Syntax](/firefly/reference/api_query_syntax.html) +- Reference: [API Query Syntax](../reference/api_query_syntax.html) - Swagger: GET /api/v1/namespaces/{ns}/messages ### Example 1: Query confirmed messages From 80bcd715896b308f8d79662c6196459c8bcf2b23 Mon Sep 17 00:00:00 2001 From: Nicko Guyer Date: Mon, 23 May 2022 17:14:06 -0400 Subject: [PATCH 2/2] Assign semver regex to env variable in docs GitHub action Signed-off-by: Nicko Guyer --- .github/workflows/docs.yml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5062a1257..bca571871 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -15,6 +15,12 @@ jobs: concurrency: group: ${{ github.workflow }}-${{ github.ref }} steps: + + # This is a regex from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string + # It is used in this GitHub action in a couple places to find semver named directories (with a 'v' on the front) + - name: Set SEMVER_REGEX + run: echo "SEMVER_REGEX='^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'" >> $GITHUB_ENV + - name: Checkout the current commit uses: actions/checkout@v3 with: @@ -51,9 +57,11 @@ jobs: echo "version: ${{ env.DOCS_VERSION }}" >> ./docs/_config.yml # Only need to build the full list of versions every time there is a new release + # This uses a regex to determine which existing directories are "versions" and should be listed in the version.json file. + # The output of this command is a version.json file containing a JSON array of all semver released versions of the docs, plus "latest" and "head" - name: Update version.json list if: github.event_name == 'release' - run: ls ./gh-pages | grep -E '^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/.$//' | sed 's/^/[/;s/$/]/' | jq '. += ["${{ env.DOCS_VERSION }}"] | sort_by(.) | reverse | . += ["latest", "head"]' > ./docs/assets/js/versions.json + run: ls ./gh-pages | grep -E ${{ env.SEMVER_REGEX }} | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/.$//' | sed 's/^/[/;s/$/]/' | jq '. += ["${{ env.DOCS_VERSION }}"] | sort_by(.) | reverse | . += ["latest", "head"]' > ./docs/assets/js/versions.json - name: Install dependencies working-directory: docs @@ -89,9 +97,10 @@ jobs: working-directory: docs run: mv _site ${{ env.DOCS_VERSION }} + # This uses a regex from to determine which existing directories are "versions" and should be copied over - name: Copy existing versions into working directory if: github.event_name == 'release' - run: ls ./gh-pages | grep -E '^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' | xargs -I '{}' mv './gh-pages/{}' ./docs + run: ls ./gh-pages | grep -E ${{ env.SEMVER_REGEX }} | xargs -I '{}' mv './gh-pages/{}' ./docs - name: Copy existing 'head' directory into working directory if: github.event_name == 'release'