From 8ce7da91f02074a1ea174a6d320183a44190b899 Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Thu, 29 Aug 2024 16:56:21 -0700 Subject: [PATCH] Document the documentation site generation process Signed-off-by: Stephen Curran --- Managing-ACA-Py-Doc-Site.md | 135 +++++++++++++++++++++++++++++++ PUBLISHING.md | 134 +++++++++++------------------- docs/testing/IntegrationTests.md | 10 +-- mkdocs.yml | 2 + scripts/prepmkdocs.sh | 4 + 5 files changed, 194 insertions(+), 91 deletions(-) create mode 100644 Managing-ACA-Py-Doc-Site.md diff --git a/Managing-ACA-Py-Doc-Site.md b/Managing-ACA-Py-Doc-Site.md new file mode 100644 index 0000000000..6a061c9041 --- /dev/null +++ b/Managing-ACA-Py-Doc-Site.md @@ -0,0 +1,135 @@ +# Managing the ACA-Py Documentation Site + +The ACA-Py documentation site is a [MkDocs Material] site generated from the +Markdown files in this repository. Whenever the `main` branch is updated or a +release branch is (possibly temporarily) created, the [publish-docs] GitHub +Action is fired, generating and publishing the documentation for the +updated/created branch. The generation process generates the static set of HTML +pages for the version in a folder in the `gh-pages` branch of this repo. The +static pages for each (other than the `main` branch) version are not updated +after creation. From time to time, some "extra" maintenance on the versions are +needed and this document describes those activities. + +[MkDocs Material]: https://squidfunk.github.io/mkdocs-material/ +[publish-docs]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/.github/workflows/publish-docs.yml + +## Generation Process + +The generation process includes the following steps as part of the GitHub Action +and mkdocs configuration. + +When the GitHub Action fires, it runs a container that carries out the following steps: + +- Checks out the triggering branch, either `main` or `docs-v` (e.g `docs-v1.0.0`). +- Runs the script [scripts/prepmkdocs.sh], which moves and updates some of the + markdown files so that they fit into the generated site. See the comments in + the scripts for details about the copying and editing done via the script. In + general, the copying of files is to put markdown files in the root folder into + the `docs` folder, and to update links that need to be changed to work on the + generated site. This allows us to have links working using the GitHub UI and + on the generated site. +- Invokes the mkdocs extension `mike` that generates the mkdocs HTML pages and + then captures and commits them into the `gh-pages` branch of the repository. + It also adds (if needed) a reference to the new version in the site's + "versions" dropdown, enabling users to pick the version of the docs they want + to look at. The process uses the [mkdocs.yml] configuration file in generating + the site. + +[scripts/prepmkdocs.sh]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/scripts/prepmkdocs.sh +[mkdocs.yml]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/mkdocs.yml + +## Preparing for a Release + +When preparing for a release (or even just a PR to `main`) you can test the +documentation site on your local clone using the following steps. The steps +assume that you have installed `mkdocs` on your system. Guidance for that can be +found in the [MkDocs Material] documentation. + +- Note the files changed in your repository that have not been committed. This + process will change and then "unchange" files in your local clone. The + "unchange" may not be perfect, so you want to be sure that no extra changed + files get into your next commit. +- Run the bash script [scripts/prepmkdocs.sh]. It will change a number of files + in your local repository. +- Run `mkdocs`. Watch for warnings of missing documents and broken links in the + startup messages. See the notes below for dealing with those issues. +- Open your browser and browse the site, looking for any issues. +- Update the documents, [mkdocs.yml] and the [scripts/prepmkdocs.sh] as needed, + repeating the generation process as needed. +- When you are happy run [scripts/prepmkdocs.sh] with the parameter `clean`. + This should undo the changes done by the script. You should check that there + no unexpected files changed that you don't want committed into the repo. + +If there are missing documents, it may be that they are new Markdown files that +have not yet been added to the [mkdocs.yml] navigation. Update that file to add +the new files, and push the changes to the repository in a pull request. There +are a few files listed below that we don't generate into the documentation site, +and they can be ignored. + +- `assets/README.md` +- `design/AnoncredsW3CCompatibility.md` +- `design/UpgradeViaApi.md` +- `features/W3cCredentials.md` + +If there are broken links, it is likely because there is a Markdown link that +works using the GitHub UI (e.g. a relative link to a file in the repo) but +doesn't on the generated site. In general there are two ways to fix these: + +- Change the link in the Markdown file so that it is a fully qualified URL vs. a + relative link, so that it works in both the GitHub UI and the generated site. +- Extend the [scripts/prepmkdocs.sh] `sed` commands so that the link differs in + the GitHub UI and the generated site -- working in both. A pain, but sometimes + needed... + +## Removing RC Releases From the Generated Site + +Documentation is added to the site for release candidates (RCs). When those +release candidates are replaced, we want to remove their documentation version +from the documentation site. In the current GitHub Action, the version +documentation is created but never deleted, so the process to remove the +documentation for the RC is manual. It would be nice to create a mechanism in +the GitHub Action to do this automatically, but its not there yet. + +To delete the documentation version, do the following: + +- In your local fork, checkout the gh-pages: `git checkout -b gh-pages --track + upstream/gh-pages` (or use whatever local branch name you want) +- Check your `git status` and make sure there are no changes in the branch -- + e.g., new files that shouldn't be added to the `gh-pages` branch. If there are + any -- delete the files so they are not added. +- Remove the folder for the RC. For example `rm -rf 1.0.0rc4` +- Edit the `versions.json` file and remove the reference to the RC release in + the file. +- Push the changes via a PR to the ACA-Py `gh-pages` branch (don't PR them into + `main`!!). +- Merge the PR and verify (after a few minutes) that the drop down no longer has + the RC in it. + +## Adding new 0.11.x Releases + +The automatic generation process from ACA-Py started with release 0.12.0. +Unfortunately, we declared release 0.11.x to be an Long Term Support version and +so we still need to add 0.11.x version documentation to the generated site. +Here's the (lousy) process to do this. Typically, [swcurran] will do this and no +one else needs to worry about it. But for completeness, here is the process: + +- Follow the instructions in the [aries-acapy-docs] repository to generate and + publish the documentation site for the new 0.11.x version. +- Have a local copy of the [aries-acapy-docs] repository. In that repo, run `git + checkout -b gh-pages --track upstream/gh-pages` to checkout a local copy of + the generated pages from that repo. +- In ACA-Py, run `git checkout -b gh-pages --track upstream/gh-pages` to create + a local branch from which you will push a PR. +- Copy the v0.11.x folder from [aries-acapy-docs] local to a new 0.11.x folder + in the ACA-Py local. Note the "v" that is on the folder in [aries-acapy-docs], + but not in ACA-Py. +- Edit the `versions.json` file to add the 0.11.x reference into the file. +- Push the changes via a PR to the ACA-Py `gh-pages` branch (don't PR them into + `main`!!). +- Merge the PR and verify (after a few minutes) that the drop down includes the + 0.11.x version. + +Ugly! The LTS for 0.11 ends in January 2025 and this process can be dropped. + +[swcurran]: https://github.com/swcurran +[aries-acapy-docs]: https://github.com/hyperledger/aries-acapy-docs diff --git a/PUBLISHING.md b/PUBLISHING.md index 2b5081c612..6cb4cbe307 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -15,86 +15,35 @@ Once ready to do a release, create a local branch that includes the following up file as necessary. On completion of the testing, run the script `./scripts/prepmkdocs.sh clean` to undo the temporary changes to the docs. Be sure to do the last `clean` step -- **DO NOT MERGE THE TEMPORARY DOC - CHANGES.** - -3. Update the CHANGELOG.md to add the new release. Only create a new section when working on the first release candidate for a new release. When transitioning from one release candidate to the next, or to an official release, just update the title and date of the change log section. - -4. Include details of the merged PRs included in this release. General process to follow: - -- Gather the set of PRs since the last release and put them into a list. A good - tool to use for this is the - [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator). - Steps: - - Create a read only GitHub token for your account on this page: - [https://github.com/settings/tokens](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token) - with a scope of `repo` / `public_repo`. - - Use a command like the following, adjusting the tag parameters as - appropriate. `docker run -it --rm -v "$(pwd)":/usr/local/src/your-app - githubchangeloggenerator/github-changelog-generator --user hyperledger - --project aries-cloudagent-python --output 0.11.0rc2.md --since-tag 0.10.4 - --future-release 0.11.1rc2 --release-branch main --token ` - - In the generated file, use only the PR list -- we don't include the list of - closed issues in the Change Log. - -In some cases, the approach above fails because of too many API calls. An -alternate approach to getting the list of PRs in the right format is to use [OpenAI ChatGPT]. - -Prepare the following ChatGPT request. Don't hit enter yet--you have to add the data. - -`Generate from this the github pull request number, the github id of the author and the title of the pull request in a tab-delimited list` - -Get a list of the merged PRs since the last release by displaying the PR list in -the GitHub UI, highlighting/copying the PRs and pasting them below the ChatGPT -request, one page after another. Hit ``, let the AI magic work, and you -should have a list of the PRs in a nice table with a `Copy` link that you should click. - -Once you have that, open this [Google Sheet] and highlight the `A1` cell and -paste in the ChatGPT data. A formula in column `E` will have the properly -formatted changelog entries. Double check the list with the GitHub UI to make -sure that ChatGPT isn't messing with you and you have the needed data. + CHANGES.** For more details see the [Managing the ACA-Py Documentation Site] document. + +3. Update the CHANGELOG.md to add the new release. Only create a new section + when working on the first release candidate for a new release. When + transitioning from one release candidate to the next, or to an official + release, just update the title and date of the change log section. + +4. Collect the details of the merged PRs included in this release -- a list of PR + title, number, link to PR, author's github ID, and a link to the author's + github account. Gathering that data can be painful. Here are is the current + easiest way to do this -- using [OpenAI ChatGPT]: + +> Prepare the following ChatGPT request. Don't hit enter yet--you have to add the data. +> +> `Generate from this the github pull request number, the github id of the author and the title of the pull request in a tab-delimited list` +> +> Get a list of the merged PRs since the last release by displaying the PR list in +> the GitHub UI, highlighting/copying the PRs and pasting them below the ChatGPT +> request, one page after another. Hit ``, let the AI magic work, and you +> should have a list of the PRs in a nice table with a `Copy` link that you should click. +> +> Once you have that, open this [Google Sheet] and highlight the `A1` cell and +> paste in the ChatGPT data. A formula in column `E` will have the properly +> formatted changelog entries. Double check the list with the GitHub UI to make +> sure that ChatGPT isn't messing with you and you have the needed data. [OpenAI ChatGPT]: https://chat.openai.com [Google Sheet]: https://docs.google.com/spreadsheets/d/1gIjPirZ42g5eM-JBtVt8xN5Jm0PQuEv91a8woRAuDEg/edit?usp=sharing -If using ChatGPT doesn't appeal to you, try this scary `sed`/command line approach: - -- Put the following commands into a file called `changelog.sed` - -``` bash -/Approved/d -/updated /d -/^$/d -/^ [0-9]/d -s/was merged.*// -/^@/d -s# by \(.*\) # [\1](https://github.com/\1)# -s/^ // -s# \#\([0-9]*\)# [\#\1](https://github.com/hyperledger/aries-cloudagent-python/pull/\1) # -s/ / /g -/^Version/d -/tasks done/d -s/^/- / -``` - -- Navigate in your browser to the paged list of PRs merged since the last - release (using in the GitHub UI a filter such as `is:pr is:merged sort:updated - merged:>2022-04-07`) and for each page, highlight, and copy the text - of only the list of PRs on the page to use in the following step. -- For each page, run the command - `sed -e :a -e '$!N;s/\n#/ #/;ta' -e 'P;D' <`, for example, `docs-v1.0.0`. + The creation of the branch triggers the execution of the [publish-docs] + GitHub Action which generates the documentation for the new release, + publishing it at [https://aca-py.org]. The GitHub Action also executes when + the `main` branch is updated via a merge, publishing an update to the `main` + branch documentation. Additional information about that documentation + publishing process and some related maintenance activities that are needed + from time to time can be found in the [Managing the ACA-Py Documentation Site] document. + +[publish-docs]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/.github/workflows/publish-docs.yml +[Managing the ACA-Py Documentation Site]: Managing-ACA-Py-Doc-Site.md +[https://aca-py.org]: https://aca-py.org -13. Update the [https://aca-py.org] website with the latest documentation by - creating a PR and tag of the latest documentation from this site. Details - are provided in the [aries-acapy-docs] repository. +13. Update the [ACA-Py Read The Docs site] by logging into Read The Docs + administration site, building a new "latest" (main branch) and activating + and building the new release by version ID. Appropriate permissions are + required to publish the new documentation version. -[https://aca-py.org]: https://aca-py.org -[aries-acapy-docs]: https://github.com/hyperledger/aries-acapy-docs +[ACA-Py Read The Docs site]: https://aries-cloud-agent-python.readthedocs.io/en/latest/ diff --git a/docs/testing/IntegrationTests.md b/docs/testing/IntegrationTests.md index a8a36f86db..338c455074 100644 --- a/docs/testing/IntegrationTests.md +++ b/docs/testing/IntegrationTests.md @@ -1,25 +1,25 @@ # Integration Test Plan Integration testing in ACA-Py consists of 3 different levels or types. -1. Interop profile (AATH) BDD tests. + +1. Interop profile (AATH) BDD tests. 2. ACA-Py specific BDD tests. 3. Scenario testing. ## Interop profile (AATH) BDD tests -Interoperability is extremely important in the aries community. When implementing or changing features that are included in the [aries interop profile](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0302-aries-interop-profile/README.md) the developer should try to add tests to this test suite. +Interoperability is extremely important in the aries community. When implementing or changing features that are included in the [aries interop profile](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0302-aries-interop-profile/README.md) the developer should try to add tests to this test suite. -These tests are contained in a separate repo [AATH](https://github.com/hyperledger/aries-agent-test-harness). They use the gherkin syntax and a http back channel. Changes to the tests need to be added and merged into this repo before they will be reflected in the automatic testing workflows. There has been a lot of work to make developing and debugging tests easier. See (AATH Dev Containers)[https://github.com/hyperledger/aries-agent-test-harness/blob/main/AATH_DEV_CONTAINERS.md#dev-containers-in-aath] +These tests are contained in a separate repo [AATH](https://github.com/hyperledger/aries-agent-test-harness). They use the gherkin syntax and a http back channel. Changes to the tests need to be added and merged into this repo before they will be reflected in the automatic testing workflows. There has been a lot of work to make developing and debugging tests easier. See (AATH Dev Containers)[https://github.com/hyperledger/aries-agent-test-harness/blob/main/AATH_DEV_CONTAINERS.md#dev-containers-in-aath]. The tests will then be ran for PR's and scheduled workflows for ACA-Py <--> ACA-Py agents. These tests are important because having them allows the AATH project to more easily test credo-ts <--> ACA-Py scenarios and ensure interoperability with mobile agents interacting with python agents. ## ACA-Py specific BDD tests -These tests leverage the [demo agent](../../demo/README.md) and also use gherkin syntax and a back channel. See [README](./BDDTests.md) +These tests leverage the [demo agent](../demo/README.md) and also use gherkin syntax and a back channel. See [README](./BDDTests.md). These tests are another tool for leveraging the demo agent and the gherkin syntax. They should not be used to test features that involve the interop profile, as they can not be used to test against other frameworks. None of the tests that are covered by the AATH tests will be ran automatically. They are here because some developers may prefer the testing strategy and can be useful for explicit testing steps and protocols not included in the interop profile. ## Scenario testing These tests utilize the minimal example [agent](https://github.com/Indicio-tech/acapy-minimal-example) produced by Indicio. They exist in the `scenarios` directory. They are very useful for running specific test plans and checking webhooks. - diff --git a/mkdocs.yml b/mkdocs.yml index aea28af754..8e5008b093 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -144,6 +144,7 @@ nav: - The askar-anoncreds Wallet Type: deploying/AnonCredsWalletType.md - Testing/Troubleshooting: - Running and Creating Unit Tests: testing/UnitTests.md + - Integration Tests: testing/IntegrationTests.md - Managing Logging: testing/Logging.md - ACA-Py Integration BDD Tests: testing/BDDTests.md - Protocol Tracing: testing/AgentTracing.md @@ -154,4 +155,5 @@ nav: - Hyperledger Code of Conduct: CODE_OF_CONDUCT.md - Security Vulnerability Reporting: SECURITY.md - Publishing an ACA-Py Release: PUBLISHING.md + - Managing the ACA-Py Documentation Site: Managing-ACA-Py-Doc-Site.md - Updating the ACA-Py ReadTheDocs Site: UpdateRTD.md diff --git a/scripts/prepmkdocs.sh b/scripts/prepmkdocs.sh index bcfc365b19..14d0a88800 100755 --- a/scripts/prepmkdocs.sh +++ b/scripts/prepmkdocs.sh @@ -13,12 +13,16 @@ if [[ "$1" == "clean" ]]; then docs/MAINTAINERS.md \ docs/PUBLISHING.md \ docs/LTS-Strategy.md \ + docs/aca-py_architecture.png \ + docs/Managing-ACA-Py-Doc-Site.md \ docs/SECURITY.md ## Update the following line to "clean" any changes made below to files that remain in the `docs` folder git checkout -- docs/README.md docs/demo/AriesOpenAPIDemo.md docs/demo/AliceGetsAPhone.md docs/features/DevReadMe.md 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 + # Copy the architecture drawing + cp aca-py_architecture.png docs # Fix references in DevReadMe.md to moved files sed -e "s#\.\./\.\./#../#g" 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