Skip to content

Commit 1d100b5

Browse files
nguyernguyer
authored
Merge pull request #1503 from kaleido-io/docs
Move doc site to new Hyperledger template
2 parents 12e03c8 + ecba933 commit 1d100b5

File tree

367 files changed

+2991
-8716
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

367 files changed

+2991
-8716
lines changed

‎.github/workflows/docs.yml

Lines changed: 42 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -12,110 +12,52 @@ jobs:
1212
runs-on: ubuntu-latest
1313
permissions:
1414
contents: write
15-
concurrency:
16-
group: ${{ github.workflow }}-${{ github.ref }}
1715
steps:
18-
19-
# This is a regex from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
20-
# It is used in this GitHub action in a couple places to find semver named directories (with a 'v' on the front)
21-
- name: Set SEMVER_REGEX
22-
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
23-
24-
- name: Checkout the current commit
16+
- name: Checkout source
2517
uses: actions/checkout@v3
2618
with:
2719
fetch-depth: 0
28-
29-
# If this is a new release, get the previous versions of the docs to build the full list of versions
30-
- name: Checkout the gh-pages branch
31-
if: github.event_name == 'release'
32-
uses: actions/checkout@v3
33-
with:
34-
ref: gh-pages
35-
path: gh-pages
36-
37-
- name: Setup Ruby
38-
uses: ruby/setup-ruby@v1
39-
with:
40-
ruby-version: '3.0'
4120

42-
- name: Install bundler
43-
run: gem install bundler:1.17.2
44-
45-
# If this was a merge to main, set the version to "head"
46-
- name: Set version env var to 'head'
47-
if: github.event_name == 'push'
48-
run: echo "DOCS_VERSION=head" >> $GITHUB_ENV
49-
50-
# If this was a release, set the version number
51-
- name: Set version env var
52-
if: github.event_name == 'release'
53-
run: echo "DOCS_VERSION=${GITHUB_REF##*/}" >> $GITHUB_ENV
54-
55-
- name: Set version in _config.yml
21+
- name: Setup Docs Deploy
5622
run: |
57-
echo "version: ${{ env.DOCS_VERSION }}" >> ./docs/_config.yml
58-
59-
# Only need to build the full list of versions every time there is a new release
60-
# This uses a regex to determine which existing directories are "versions" and should be listed in the version.json file.
61-
# 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"
62-
- name: Update version.json list
63-
if: github.event_name == 'release'
64-
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
65-
66-
- name: Install dependencies
67-
working-directory: docs
68-
run: bundle install
69-
70-
- name: Build doc site version
71-
working-directory: docs
72-
run: bundle exec jekyll build --baseurl /firefly/${{ env.DOCS_VERSION }}
73-
74-
- name: Check the docs for broken links (root)
75-
if: github.event_name == 'pull_request'
76-
working-directory: docs
77-
run: bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site
78-
79-
- name: Check the docs for broken links (version)
80-
if: github.event_name != 'pull_request'
81-
working-directory: docs
82-
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
83-
84-
- name: Deploy docs (version)
85-
if: github.event_name == 'push'
86-
uses: peaceiris/actions-gh-pages@v3
87-
with:
88-
github_token: ${{ secrets.GITHUB_TOKEN }}
89-
publish_branch: gh-pages
90-
publish_dir: ./docs/_site
91-
destination_dir: ./${{ env.DOCS_VERSION }}
92-
93-
## FINAL STEPS TO COMPLETE IF THIS WAS A NEW RELEASE ##
94-
95-
- name: Copy new version into version directory
96-
if: github.event_name == 'release'
97-
working-directory: docs
98-
run: mv _site ${{ env.DOCS_VERSION }}
99-
100-
# This uses a regex from to determine which existing directories are "versions" and should be copied over
101-
- name: Copy existing versions into working directory
102-
if: github.event_name == 'release'
103-
run: ls ./gh-pages | grep -E ${{ env.SEMVER_REGEX }} | xargs -I '{}' mv './gh-pages/{}' ./docs
104-
105-
- name: Copy existing 'head' directory into working directory
106-
if: github.event_name == 'release'
107-
run: mv ./gh-pages/head ./docs
108-
109-
- name: Build doc site (latest)
110-
if: github.event_name == 'release'
111-
working-directory: docs
112-
run: bundle exec jekyll build --baseurl /firefly
113-
114-
- name: Deploy docs (latest)
115-
if: github.event_name == 'release'
116-
uses: peaceiris/actions-gh-pages@v3
117-
with:
118-
github_token: ${{ secrets.GITHUB_TOKEN }}
119-
publish_branch: gh-pages
120-
publish_dir: ./docs/_site
23+
git config --global user.name "GitHub Actions"
24+
git config --global user.email "[email protected]"
12125
26+
- name: Check if this is the latest release
27+
run: |
28+
LATEST_TAG=$(
29+
curl -L \
30+
-H "Accept: application/vnd.github+json" \
31+
-H "Authorization: Bearer ${{ github.token }}" \
32+
-H "X-GitHub-Api-Version: 2022-11-28" \
33+
https://api.github.com/repos/${{ github.repository }}/releases/latest \
34+
| jq -r '.tag_name'
35+
)
36+
IS_LATEST=${{ env.LATEST_TAG == github.event.release.tag_name }}
37+
echo This release is: "${{ github.event.release.tag_name }}"
38+
echo The latest release is: "$LATEST_TAG"
39+
echo "IS_LATEST_RELEASE=$IS_LATEST" >> "$GITHUB_ENV"
40+
41+
- name: Install docs dependencies
42+
working-directory: doc-site
43+
run: pip install -r requirements.txt
44+
45+
- name: Update doc site for release
46+
if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE != 'true' }}
47+
working-directory: doc-site
48+
run: mike deploy ${{ github.event.release.tag_name }} --push
49+
50+
- name: Update doc site for latest release
51+
if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE == 'true' }}
52+
working-directory: doc-site
53+
run: mike deploy ${{ github.event.release.tag_name }} latest --push
54+
55+
- name: Update doc site for `main` branch
56+
if: ${{ github.event_name == 'push' }}
57+
working-directory: doc-site
58+
run: mike deploy head --push
59+
60+
- name: Test building the doc site but do not deploy it
61+
if: ${{ github.event_name == 'pull_request' }}
62+
working-directory: doc-site
63+
run: mkdocs build

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ __debug*
1313
containerlogs
1414
.vscode/*.log
1515
.idea
16+
doc-site/site

‎Makefile

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ GOGC=30
1414

1515
all: build test go-mod-tidy
1616
test: deps lint
17-
$(VGO) test ./internal/... ./pkg/... ./cmd/... ./docs ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS}
17+
$(VGO) test ./internal/... ./pkg/... ./cmd/... ./doc-site ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS}
1818
coverage.html:
1919
$(VGO) tool cover -html=coverage.txt
2020
coverage: test coverage.html
@@ -99,12 +99,12 @@ clean:
9999
deps:
100100
$(VGO) get
101101
reference:
102-
$(VGO) test ./internal/apiserver ./internal/reference ./docs -timeout=10s -tags reference
102+
$(VGO) test ./internal/apiserver ./internal/reference ./doc-site -timeout=10s -tags reference
103103
manifest:
104104
./manifestgen.sh
105105
docker:
106106
./docker_build.sh --load $(DOCKER_ARGS)
107107
docker-multiarch:
108108
./docker_build.sh --platform linux/amd64,linux/arm64 $(DOCKER_ARGS)
109109
docs: .ALWAYS
110-
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
110+
cd doc-site && mkdocs build

‎doc-site/.github/ISSUE_TEMPLATE/bug-report.yml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: 🐞 Bug
2+
description: File a bug/issue
3+
title: "bug: "
4+
labels: [bug]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
_The more information you share, the faster we can help you._
10+
Prior to opening the issue, please make sure that you:
11+
- Use English (EN/US) to communicate.
12+
- Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
13+
14+
- type: textarea
15+
id: problem
16+
attributes:
17+
label: What happened?
18+
description: |
19+
Please provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner.
20+
If this matter is security related, please disclose it privately via [email protected]
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: expected
26+
attributes:
27+
label: What did you expect to happen?
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: repro
33+
attributes:
34+
label: How can we reproduce it (as minimally and precisely as possible)?
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: additional
40+
attributes:
41+
label: Anything else we need to know?
42+
43+
- type: textarea
44+
id: osVersion
45+
attributes:
46+
label: OS version
47+
value: |
48+
<details>
49+
50+
```console
51+
# On Linux:
52+
$ cat /etc/os-release
53+
# paste output here
54+
$ uname -a
55+
# paste output here
56+
57+
# On Windows:
58+
C:\> wmic os get Caption, Version, BuildNumber, OSArchitecture
59+
# paste output here
60+
```
61+
62+
</details>

‎doc-site/.github/ISSUE_TEMPLATE/config.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Support Request
4+
url: https://discord.gg/hyperledger
5+
about: Support request or question relating to Hyperledger Docs

‎doc-site/.github/ISSUE_TEMPLATE/enhancement.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Enhancement Tracking Issue
2+
description: Provide supporting details for an enhancement
3+
labels: [enhancement]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
_The more information you share, the faster we can help you._
9+
Prior to opening the issue, please make sure that you:
10+
- Use English (EN/US) to communicate.
11+
- Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
12+
13+
- type: textarea
14+
id: enhancement
15+
attributes:
16+
label: What would you like to be added?
17+
description: |
18+
A clear and concise description of what you want to happen.
19+
validations:
20+
required: true
21+
22+
- type: textarea
23+
id: rationale
24+
attributes:
25+
label: Why is this needed?
26+
validations:
27+
required: true

‎doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: "Documentation Issue"
2+
description: Issues related to documentation.
3+
title: "docs: "
4+
labels: [documentation]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
_The more information you share, the faster we can help you._
10+
Prior to opening the issue, please make sure that you:
11+
- Use English (EN/US) to communicate.
12+
- Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue.
13+
14+
- type: textarea
15+
id: current-state
16+
attributes:
17+
label: Current State
18+
description: Describe the current state of the documentation.
19+
placeholder: |
20+
The documentation for the API in this page (url) is missing ...
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: desired-state
25+
attributes:
26+
label: Desired State
27+
description: Describe the desired state the documentation should be in.
28+
placeholder: |
29+
Add here ...
30+
validations:
31+
required: true

‎doc-site/.github/labels.yml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
- name: bug
2+
description: Something isn't working
3+
color: b60205
4+
- name: documentation
5+
description: Improvements or additions to documentation
6+
color: 0052cc
7+
- name: duplicate
8+
description: This issue or pull request already exists
9+
color: 9c99a3
10+
- name: enhancement
11+
description: New feature or request
12+
color: 1dbfcf
13+
- name: good first issue
14+
description: Good for newcomers
15+
color: 8141f0
16+
- name: help wanted
17+
description: Extra attention is needed
18+
color: 0ac492
19+
- name: invalid
20+
description: This doesn't seem right
21+
color: e6da05
22+
- name: needs triage
23+
description: New issue that has not yet been looked at
24+
color: 69a6d1
25+
- name: question
26+
description: Further information is requested
27+
color: 8a23b0
28+
- name: wontfix
29+
description: This will not be worked on
30+
color: ccb5ab
31+
- name: stale
32+
description: no commits in last 30 days
33+
color: 382c0d
34+
- name: awaiting response
35+
description: Waiting for user response
36+
color: d1821b

‎doc-site/.github/pull_request_template.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<!-- Thanks for sending a pull request! -->
2+
3+
## Proposed changes
4+
5+
Please include a summary of the changes here and why we need those changes. And also let us know which issue is fixed.
6+
7+
Fixes # <issue_number_here>
8+
9+
<hr>
10+
11+
## Types of changes
12+
13+
<!-- to mark a point done, place an x in square brackets. eg [x]-->
14+
<!-- - [x] done with this task-->
15+
<!----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----->
16+
17+
- [ ] Bug fix
18+
- [ ] New feature added
19+
- [ ] Documentation Update
20+
21+
<hr>
22+
23+
## Please make sure to follow these points
24+
25+
<!-- to mark a point done, place an x in square brackets. eg [x]-->
26+
<!-- - [x] done with this task-->
27+
<!----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----->
28+
29+
- [ ] I have read the contributing guidelines.
30+
- [ ] I have performed a self-review of my own code or work.
31+
- [ ] I have commented my code, particularly in hard-to-understand areas.
32+
- [ ] My changes generates no new warnings.
33+
- [ ] My Pull Request title is in format <code>< issue name ></code> eg <code>Added links in the documentation</code>.
34+
- [ ] I have added tests that prove my fix is effective or that my feature works.
35+
36+
<hr>
37+
38+
## Screenshots (If Applicable)
39+
40+
<hr>
41+
42+
43+
## Other Information
44+
45+
Any message for the reviewer or kick off the discussion by explaining why you considered this particular solution, any alternatives etc.

0 commit comments

Comments
 (0)