From aef1fd64c999ee16b731eaca49420e8dca857673 Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Fri, 12 Apr 2024 07:42:53 -0700 Subject: [PATCH] Some updates to the mkdocs publishing process Signed-off-by: Stephen Curran --- .github/workflows/publish-docs.yml | 8 ++------ scripts/prepmkdocs.sh | 27 +++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 6 deletions(-) create mode 100755 scripts/prepmkdocs.sh diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index d715afeed3..54dc8c7577 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -37,12 +37,8 @@ jobs: echo "${{ github.ref }}" # Extract the version and if it is in `docs-v` form, strip that off the version VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,' -e 's/^docs-v//') - # Copy all of the root level md files into the docs folder for deployment, tweaking the relative paths - for i in *.md; do sed -e "s#docs/#./#g" $i >docs/$i; done - # Fix references in DevReadMe.md to moved files - sed -e "s#\.\./\.\./#../#" docs/features/DevReadMe.md >tmp.md; mv tmp.md docs/features/DevReadMe.md - # Fix image references in demo documents so they work in GitHub and mkdocs - for i in docs/demo/AriesOpenAPIDemo.md docs/demo/AliceGetsAPhone.md; do sed -e "s#src=.collateral#src=\"../collateral#" $i >$i.tmp; mv $i.tmp $i; done + # Run a script to prepare all the files that have to be moved/updated to publish cleanly + ./scripts/prepmkdocs.sh # Populate overrides for the current version, and then remove to not apply if VERSION is main branch OVERRIDE=overrides/main.html echo -e "{% extends \"base.html\" %}\n\n{% block outdated %}\n You are viewing the documentation for ACA-Py Release $VERSION.\n{% endblock %}" >$OVERRIDE diff --git a/scripts/prepmkdocs.sh b/scripts/prepmkdocs.sh new file mode 100755 index 0000000000..eeebcf8e05 --- /dev/null +++ b/scripts/prepmkdocs.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +# A script to prep for testing of mkdocs generation, and then to clean up after +# Replicates the file preparation done in the .github/workflows/publish-docs Git Hub Action +# TODO: Move all the prepaanupCalled from the GHA to do all of the work being done there. +# +# Add argument "clean" to undo these changes when just being used for testing. +# WARNING -- does a `git checkout -- docs` so you will lose any others changes you make!!! + +if [[ "$1" == "clean" ]]; then + rm -f docs/CHANGELOG.md \ + docs/CODE_OF_CONDUCT.md \ + docs/CONTRIBUTING.md \ + docs/MAINTAINERS.md \ + docs/PUBLISHING.md \ + docs/SECURITY.md + git checkout -- docs +else + # Copy all of the root level md files into the docs folder for deployment, tweaking the relative paths + for i in *.md; do sed -e "s#docs/#./#g" $i >docs/$i; done + # Fix references in DevReadMe.md to moved files + sed -e "s#\.\./\.\./#../#" docs/features/DevReadMe.md >tmp.md; mv tmp.md docs/features/DevReadMe.md + # Fix image references in demo documents so they work in GitHub and mkdocs + for i in docs/demo/AriesOpenAPIDemo.md docs/demo/AliceGetsAPhone.md; do sed -e "s#src=.collateral#src=\"../collateral#" $i >$i.tmp; mv $i.tmp $i; done + # Cleanup indented bullets in at least the CHANGELOG.md so they look right when published + for i in docs/CHANGELOG.md; do sed -e 's#^ - # - #' $i >$i.tmp; mv $i.tmp $i; done +fi