Merge pull request #1503 from kaleido-io/docs

Move doc site to new Hyperledger template
hyperledger · Apr 25, 2024 · 1d100b5 · 1d100b5
2 parents 12e03c8 + ecba933
commit 1d100b5
Show file tree

Hide file tree

Showing 367 changed files with 2,991 additions and 8,716 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -12,110 +12,52 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-    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
+      - name: Checkout source
         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
-        with:
-          ruby-version: '3.0'
 
-      - name: Install bundler
-        run: gem install bundler:1.17.2
-
-      # 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
+      - name: Setup Docs Deploy
         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
-      # 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 ${{ 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
-        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 --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site
-
-      - name: Check the docs for broken links (version)
-        if: github.event_name != 'pull_request'
-        working-directory: docs
-        run: bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/${{ env.DOCS_VERSION }}/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site
-
-      - 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
-          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 }}
-
-      # 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 ${{ env.SEMVER_REGEX }} | 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
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
 
+      - name: Check if this is the latest release
+        run: |
+          LATEST_TAG=$(
+            curl -L \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${{ github.token }}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              https://api.github.com/repos/${{ github.repository }}/releases/latest \
+              | jq -r '.tag_name'
+          )
+          IS_LATEST=${{ env.LATEST_TAG == github.event.release.tag_name }}
+          echo This release is: "${{ github.event.release.tag_name }}"
+          echo The latest release is: "$LATEST_TAG"
+          echo "IS_LATEST_RELEASE=$IS_LATEST" >> "$GITHUB_ENV"
+
+      - name: Install docs dependencies
+        working-directory: doc-site
+        run: pip install -r requirements.txt
+
+      - name: Update doc site for release
+        if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE != 'true' }}
+        working-directory: doc-site
+        run: mike deploy ${{ github.event.release.tag_name }} --push
+
+      - name: Update doc site for latest release
+        if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE == 'true' }}
+        working-directory: doc-site
+        run: mike deploy ${{ github.event.release.tag_name }} latest --push
+
+      - name: Update doc site for `main` branch
+        if: ${{ github.event_name == 'push' }}
+        working-directory: doc-site
+        run: mike deploy head --push
+
+      - name: Test building the doc site but do not deploy it
+        if: ${{ github.event_name == 'pull_request' }}
+        working-directory: doc-site
+        run: mkdocs build
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,4 @@ __debug*
 containerlogs
 .vscode/*.log
 .idea
+doc-site/site
diff --git a/Makefile b/Makefile
@@ -14,7 +14,7 @@ GOGC=30
 
 all: build test go-mod-tidy
 test: deps lint
-		$(VGO) test ./internal/... ./pkg/... ./cmd/... ./docs ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS}
+		$(VGO) test ./internal/... ./pkg/... ./cmd/... ./doc-site ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS}
 coverage.html:
 		$(VGO) tool cover -html=coverage.txt
 coverage: test coverage.html
@@ -99,12 +99,12 @@ clean:
 deps:
 		$(VGO) get
 reference:
-		$(VGO) test ./internal/apiserver ./internal/reference ./docs -timeout=10s -tags reference
+		$(VGO) test ./internal/apiserver ./internal/reference ./doc-site -timeout=10s -tags reference
 manifest:
 		./manifestgen.sh
 docker:
 		./docker_build.sh --load $(DOCKER_ARGS)
 docker-multiarch:
 		./docker_build.sh --platform linux/amd64,linux/arm64 $(DOCKER_ARGS) 
 docs: .ALWAYS
-		cd docs && bundle install && bundle exec jekyll build && bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site
+		cd doc-site && mkdocs build
diff --git a/doc-site/.github/ISSUE_TEMPLATE/bug-report.yml b/doc-site/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,62 @@
+name: 🐞 Bug
+description: File a bug/issue
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        _The more information you share, the faster we can help you._
+        Prior to opening the issue, please make sure that you:
+        - Use English (EN/US) to communicate.
+        - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: |
+        Please provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner.
+        If this matter is security related, please disclose it privately via [email protected]
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: How can we reproduce it (as minimally and precisely as possible)?
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Anything else we need to know?
+
+  - type: textarea
+    id: osVersion
+    attributes:
+      label: OS version
+      value: |
+        <details>
+
+        ```console
+        # On Linux:
+        $ cat /etc/os-release
+        # paste output here
+        $ uname -a
+        # paste output here
+
+        # On Windows:
+        C:\> wmic os get Caption, Version, BuildNumber, OSArchitecture
+        # paste output here
+        ```
+
+        </details>
diff --git a/doc-site/.github/ISSUE_TEMPLATE/config.yml b/doc-site/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Support Request
+    url: https://discord.gg/hyperledger
+    about: Support request or question relating to Hyperledger Docs
diff --git a/doc-site/.github/ISSUE_TEMPLATE/enhancement.yml b/doc-site/.github/ISSUE_TEMPLATE/enhancement.yml
@@ -0,0 +1,27 @@
+name: Enhancement Tracking Issue
+description: Provide supporting details for an enhancement
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        _The more information you share, the faster we can help you._
+        Prior to opening the issue, please make sure that you:
+        - Use English (EN/US) to communicate.
+        - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
+
+  - type: textarea
+    id: enhancement
+    attributes:
+      label: What would you like to be added?
+      description: |
+        A clear and concise description of what you want to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: rationale
+    attributes:
+      label: Why is this needed?
+    validations:
+      required: true
diff --git a/doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml b/doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml
@@ -0,0 +1,31 @@
+name: "Documentation Issue"
+description: Issues related to documentation.
+title: "docs: "
+labels: [documentation]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        _The more information you share, the faster we can help you._
+        Prior to opening the issue, please make sure that you:
+        - Use English (EN/US) to communicate.
+        - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
+
+  - type: textarea
+    id: current-state
+    attributes:
+      label: Current State
+      description: Describe the current state of the documentation.
+      placeholder: |
+        The documentation for the API in this page (url) is missing ...
+    validations:
+      required: true
+  - type: textarea
+    id: desired-state
+    attributes:
+      label: Desired State
+      description: Describe the desired state the documentation should be in.
+      placeholder: |
+        Add here ...
+    validations:
+      required: true
diff --git a/doc-site/.github/labels.yml b/doc-site/.github/labels.yml
@@ -0,0 +1,36 @@
+- name: bug
+  description: Something isn't working
+  color: b60205
+- name: documentation
+  description: Improvements or additions to documentation
+  color: 0052cc
+- name: duplicate
+  description: This issue or pull request already exists
+  color: 9c99a3
+- name: enhancement
+  description: New feature or request
+  color: 1dbfcf
+- name: good first issue
+  description: Good for newcomers
+  color: 8141f0
+- name: help wanted
+  description: Extra attention is needed
+  color: 0ac492
+- name: invalid
+  description: This doesn't seem right
+  color: e6da05
+- name: needs triage
+  description: New issue that has not yet been looked at
+  color: 69a6d1
+- name: question
+  description: Further information is requested
+  color: 8a23b0
+- name: wontfix
+  description: This will not be worked on
+  color: ccb5ab
+- name: stale
+  description: no commits in last 30 days
+  color: 382c0d
+- name: awaiting response
+  description: Waiting for user response
+  color: d1821b
diff --git a/doc-site/.github/pull_request_template.md b/doc-site/.github/pull_request_template.md
@@ -0,0 +1,45 @@
+<!--  Thanks for sending a pull request! -->
+
+## Proposed changes
+
+Please include a summary of the changes here and why we need those changes. And also let us know which issue is fixed. 
+
+Fixes # <issue_number_here>
+
+<hr>
+
+## Types of changes
+
+<!-- to mark a point done, place an x in square brackets. eg [x]-->
+<!-- - [x] done with this task-->
+<!----Please delete options that are not relevant. And in order to tick the check box just but x inside them for example [x] like this----->
+
+- [ ] Bug fix 
+- [ ] New feature added
+- [ ] Documentation Update 
+
+<hr>
+
+## Please make sure to follow these points 
+
+<!-- to mark a point done, place an x in square brackets. eg [x]-->
+<!-- - [x] done with this task-->
+<!----Please delete options that are not relevant. And in order to tick the check box just but x inside them for example [x] like this----->
+
+- [ ] I have read the contributing guidelines.
+- [ ] I have performed a self-review of my own code or work.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] My changes generates no new warnings.
+- [ ] My Pull Request title is in format <code>< issue name ></code> eg <code>Added links in the documentation</code>.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+
+<hr>
+
+## Screenshots (If Applicable)
+
+<hr>
+
+
+## Other Information
+
+Any message for the reviewer or kick off the discussion by explaining why you considered this particular solution, any alternatives etc.