From ff6e5afa5e12df611489a494f2b07d04b017ec00 Mon Sep 17 00:00:00 2001 From: Jennifer Bell Date: Fri, 14 Jun 2024 17:00:40 +0000 Subject: [PATCH] chore(docs): add openapi specs to docs Primary Changes 1. Updated deploy_docs workflow to generate markdown for openapi specs files present across packages Secondary Changes required to incorporate 1) 2. Added docs/scripts/publish_openapi.py to generate markdown 3. Added swagger-ui-tag plugin to mkdocs 4. Updated docs/requirements.txt for the above plugin to be downloaded. Signed-off-by: Jennifer Bell --- .github/workflows/deploy_docs.yml | 17 +++++++ .gitignore | 1 + docs/docs/index.md | 1 + docs/docs/references/openapi/index.md | 1 + docs/mkdocs.yml | 4 +- docs/requirements.txt | 1 + docs/scripts/publish_openapi.py | 73 +++++++++++++++++++++++++++ 7 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/docs/references/openapi/index.md create mode 100644 docs/scripts/publish_openapi.py diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 7fcd1bde22..692ef60507 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -8,16 +8,27 @@ on: push: branches: - main + paths: - 'docs/**' # Allows you to run this workflow manually from the Actions tab workflow_dispatch: + +env: + SITE_URL: https://${{ github.repository_owner }}.github.io/cacti + NODEJS_VERSION: v18.18.2 + jobs: deploy-docs: runs-on: ubuntu-22.04 steps: + - name: Use Node.js ${{ env.NODEJS_VERSION }} + uses: actions/setup-node@v4.0.2 + with: + node-version: ${{ env.NODEJS_VERSION }} + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v4.1.1 @@ -30,6 +41,12 @@ jobs: - name: Install dependencies run: pip install -r requirements.txt working-directory: docs + + - name: Build packages + run: npm run configure + + - name: Build markdown for openapi specs + run: 'python3 docs/scripts/publish_openapi.py' - name: Build and publish run: git pull && mkdocs gh-deploy diff --git a/.gitignore b/.gitignore index 4a3fdb7562..3a13ee5681 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ target/ .DS_Store node_modules/ docs/main +docs/docs/references/openapi logs/ jspm_packages/ generated-sources/ diff --git a/docs/docs/index.md b/docs/docs/index.md index d8d5f20abd..7b17821425 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -29,6 +29,7 @@ Client libraries and examples are provided in the following languages: JavaScrip * [Weaver RFCs](https://github.com/hyperledger/cacti/tree/main/weaver/rfcs) * [Running pipelines with Cactus packages](./cactus/) * [Running pipelines with Weaver packages](./weaver/) +* [Open API Specifications](./references/openapi/index.md) !!! note diff --git a/docs/docs/references/openapi/index.md b/docs/docs/references/openapi/index.md new file mode 100644 index 0000000000..88461f1929 --- /dev/null +++ b/docs/docs/references/openapi/index.md @@ -0,0 +1 @@ +# THIS PAGE GENERATED AUTOMATICALLY IN CI by docs/scripts/publish_openapi.py \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 66fdee17ec..31d0c3bdc4 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Using and Developing with Hyperledger Cacti -site_url: https://hyperledger.github.io/cacti +site_url: !ENV [SITE_URL, 'https://hyperledger.github.io/cacti'] repo_name: hyperledger/cacti repo_url: https://github.com/hyperledger/cacti theme: @@ -74,6 +74,7 @@ markdown_extensions: - pymdownx.tilde plugins: - search + - swagger-ui-tag - mike extra: analytics: @@ -192,6 +193,7 @@ nav: - Business Usage: references/business.md - Project Best Practices: references/best-practices.md - GitHub Contributions: references/github.md + - OpenAPI Specs: references/openapi/index.md - Contributing: - How to Contribute: contributing/how-to-contribute.md - Reporting a Bug: contributing/reporting-a-bug.md diff --git a/docs/requirements.txt b/docs/requirements.txt index 04ebb9bbf7..6419177139 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ mkdocs-material mike +mkdocs-swagger-ui-tag \ No newline at end of file diff --git a/docs/scripts/publish_openapi.py b/docs/scripts/publish_openapi.py new file mode 100644 index 0000000000..afb46f5641 --- /dev/null +++ b/docs/scripts/publish_openapi.py @@ -0,0 +1,73 @@ +import os +import os.path +import subprocess +import json +import shutil + +# Package openapi markdown for publishing as documentation +# +# - Copies any package openapi.json file in the dist directory to docs/docs/openapi/json +# - Generates an openapi .md file to view the openapi.json file in docs/docs/openapi +# - Generates an index file of all openapi markdown files, grouped by base directory + +apis_by_group = {} + +doc_dir = "docs/docs/references/openapi" +json_dir = f"{doc_dir}/json" + +def write_mdfile(component, src): + mdfile_name = f"{doc_dir}/{component}_openapi.md" + with open(mdfile_name, 'w') as f: + f.write(f"") + return mdfile_name + +def copy_openapi(component, openapi_file): + new_filename = f"json/{component}-openapi.json" + shutil.copy(openapi_file, f"{doc_dir}/{new_filename}") + return new_filename + +def publish_openapi(component, openapi_file): + src_file = copy_openapi(component, openapi_file) + md_file = write_mdfile(component, src_file) + +def write_index(api_groups): + with open(f"{doc_dir}/index.md", 'w') as f: + f.write(f"---\n") + f.write("title: All Cacti Open API Specifications\n") + f.write("---\n") + groups = list(api_groups.keys()) + groups.sort(reverse=True) + for group in groups: + components = api_groups[group] + f.write(f"##{group.capitalize()}\n") + components.sort() + for component in components: + f.write(f" * [{component}](./{component}_openapi.md)\n") + +def get_openapi_files(root_dir): + openapi_files = [] + for dirpath, dirnames, filenames in os.walk(root_dir + "/dist"): + for filename in [f for f in filenames if f.endswith("openapi.json")]: + openapi_files.append(os.path.join(dirpath, filename)) + return openapi_files + + +if not os.path.exists(json_dir): + os.makedirs(json_dir) + +package_list_str = subprocess.run(["npx lerna ls --json"], shell=True, capture_output=True, text=True) +package_list = json.loads(package_list_str.stdout) + +for package in package_list: + location_path = package['location'].split('/') + root_dir = len(location_path) - location_path[::-1].index('cacti') # no rindex implemented + package_group = location_path[root_dir] + for openapi_file in get_openapi_files(package['location']): + if not package_group in apis_by_group: + apis_by_group[package_group] = [] + package_basename = package['name'].replace('@hyperledger/','') + publish_openapi(package_basename, openapi_file) + print(f"{package_group} : {package_basename}") + apis_by_group[package_group].append(package_basename) + +write_index(apis_by_group) \ No newline at end of file