Skip to content

Commit

Permalink
chore(docs): add openapi specs to docs
Browse files Browse the repository at this point in the history
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 <jenniferlianne@gmail.com>
  • Loading branch information
Jennifer Bell authored and petermetz committed Jun 28, 2024
1 parent 8896518 commit ff6e5af
Show file tree
Hide file tree
Showing 7 changed files with 97 additions and 1 deletion.
17 changes: 17 additions & 0 deletions .github/workflows/deploy_docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ target/
.DS_Store
node_modules/
docs/main
docs/docs/references/openapi
logs/
jspm_packages/
generated-sources/
Expand Down
1 change: 1 addition & 0 deletions docs/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/docs/references/openapi/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# THIS PAGE GENERATED AUTOMATICALLY IN CI by docs/scripts/publish_openapi.py
4 changes: 3 additions & 1 deletion docs/mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -74,6 +74,7 @@ markdown_extensions:
- pymdownx.tilde
plugins:
- search
- swagger-ui-tag
- mike
extra:
analytics:
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
mkdocs-material
mike
mkdocs-swagger-ui-tag
73 changes: 73 additions & 0 deletions docs/scripts/publish_openapi.py
Original file line number Diff line number Diff line change
@@ -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"<swagger-ui src=\"./{src}\"/>")
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)

0 comments on commit ff6e5af

Please sign in to comment.