{"id":19901909,"url":"https://github.com/hyperledger-aries/aries-acapy-docs","last_synced_at":"2025-05-02T23:32:06.768Z","repository":{"id":147563311,"uuid":"588321679","full_name":"hyperledger/aries-acapy-docs","owner":"hyperledger","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-02T23:14:04.000Z","size":41714,"stargazers_count":2,"open_issues_count":1,"forks_count":4,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-08-03T01:10:57.036Z","etag":null,"topics":["aca-py"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperledger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-12T21:07:56.000Z","updated_at":"2024-07-29T20:16:55.000Z","dependencies_parsed_at":"2023-10-16T12:59:27.860Z","dependency_job_id":"ea781c10-0f45-478c-925d-916d056054ef","html_url":"https://github.com/hyperledger/aries-acapy-docs","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Faries-acapy-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Faries-acapy-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Faries-acapy-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Faries-acapy-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperledger","download_url":"https://codeload.github.com/hyperledger/aries-acapy-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224341304,"owners_count":17295272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aca-py"],"created_at":"2024-11-12T20:16:35.020Z","updated_at":"2025-05-02T23:32:00.756Z","avatar_url":"https://github.com/hyperledger.png","language":"Shell","readme":"# Aries ACA-Py Docs\n\n**Go to [https://aca-py.org] to access the documentation for recent [Aries Cloud Agent Python] releases.**\n**Go to [https://history.aca-py.org] to access Aries Cloud Agent Python documentation up through version 0.11.x.**\n\nThis repository is used to publish documentation for historical (pre-0.12.x)\nreleases of [Aries Cloud Agent Python] documentation to the site\n[https://history.aca-py.org]. The documentation in this site is **NOT**\nmaintained here. Rather, the documents for these past ACA-Py releases are\nextracted from the ACA-Py repository via a script and then saved to a branch in\nthis repository. Each version branch in this repository is published as a\nversion of the documentation on the public site. The \"main\" branch of this site\npoints to the latest historical release -- the most recent 0.11.x release.\n\n[Aries Cloud Agent Python]: https://github.com/hyperledger/aries-cloudagent-python\n[https://aca-py.org]: https://aca-py.org\n[https://history.aca-py.org]: https://history.aca-py.org\n\nDetails of how to add releases and update main are described in this document.\n\nThe documentation site is published following the Hyperledger Foundation best\npractices using MkDocs (documentation at [mkdocs.org](https://www.mkdocs.org/))\nand the theme Material for MkDocs (documentation at [Material for MkDocs]).\n\nIn general, only the ACA-Py Maintainers should update this site. Those wanting\nto contribute to the docs themselves should do so in the [Aries Cloud Agent\nPython] repository.\n\n[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/\n[Mike]: https://github.com/jimporter/mike\n\n## Prerequisites\n\nTo test the documents and update the published site, the following tools are needed:\n\n- A Bash shell\n- Python 3 or a Docker environment\n- git\n- The [Material for Mkdocs] theme.\n- The [Mike] MkDocs plugin for publishing versions to gh-pages.\n  - Not used locally, but referenced in the `mkdocs.yml` file and needed for\n    deploying the site to gh-pages.\n\nWe assume that anyone using this will have a least up to `git` installed locally already.\n\nThe Mkdocs-related items can be installed locally, as described in the [Material\nfor Mkdocs] installation instructions. The short, case-specific version of those\ninstructions follow:\n\n```bash\npip install -r requirements.txt\n```\n\nAlternatively, you can use Docker as described in the [Material for Mkdocs]\ninstallation instructions. You can use the Dockerfile here to build a local\ncontainer:\n\n```bash\n# Create a local container image with the necessary requirements\ndocker build -t squidfunk/mkdocs-material .\n```\n\nThe following command run `mkdocs` when needed:\n\n```bash\ndocker run --rm -it -p 4444:8000 --name mkdocs-material -v ${PWD}:/docs squidfunk/mkdocs-material\n```\n\nReplace the `4444` with the port you want to use.  It may be useful to create an alias for running\nthe docker container so that you can run `mkdocs` commands such as:\n\n```bash\nalias mkdocs='docker run --rm -it -p 4444:8000 --name mkdocs-material -v ${PWD}:/docs squidfunk/mkdocs-material'\n```\n\nThe steps below assume you setup an alias like that.\n\n### Verify Setup\n\nTo verify your setup, check that you can run `mkdocs` by running the command `mkdocs --help` to see the help text.\n\n### Useful MkDocs Commands\n\nThe commands you will usually use with `mkdocs` are:\n\n- `mkdocs build` -- build the to-be-published site using the `mkdocs.yml` configuration and the docs files in the `\\docs` folder.\n- `mkdocs` -- build the docs, and run a server that will deploy the site to your\n  localhost, on the port you specified (e.g.,\n  [http://localhost:4444](http://localhost:4444)).\n\n## Overview: Release Documentation Generator\n\nThe steps to generate the documents for a given release are quite complex\n(overly complex -- help to make them easier are welcome), so the following steps\nthrough the process the basic process of preparing any individual releaese.\nAdditional checklists are then given for the least complicated, process of\nupdating the \"main\" version the docs, through to adding a new release, and\nupdating an existing release.\n\nThe actual generation of any particular release involves running in the local\nclone of your fork the bash script `./build-docs.sh` in the root folder. The\nscript takes on an argument pair (`-t \u003ctag\u003e`) to specify the ACA-Py tag to be\nused in generating docs for a particular tag. As you will see, each tag is\ngenerated into a different branch in this repository that corresponds to the\nACA-Py release tag so you need to first be on the right branch in your local\nclone, and specify the corresponding ACA-Py tag.\n\nThe steps performed by the build-docs.sh script are:\n\n- Clone ACA-Py at the given `\u003ctag\u003e` (arg `-t \u003ctag\u003e`) into the `/tmp` folder of this repository.\n- Execute the `./scripts/copyFixMDs.sh` script.\n\nThe `./scripts/copyFixMDs.sh` script, which will be unique for each version of\nACA-Py (hence the branches in this repo per ACA-Py tag) does the following:\n\n- Deletes the current contents of the `/docs` folder in the repository.\n- Removes from the `mkdocs.yml` file the `nav:` section of the file.\n- Adds in a new `nav:` section in the `mkdocs.yml` that is inline in the script.\n- Executes a series of either `cp` commands or `sed` pipelines to extract a\n  documentation file from the `/tmp` clone of ACA-Py into the `/docs` folder of\n  this repo.\n\nIdeally, that happens without errors, but if there are errors, fix them up,\nusually by patching the document from `/tmp` via a sed pipeline as it is\nduplicated in `/docs`. See the [guidance below on fixing\nerrors](#fixing-errors).\n\nOnce the errors are cleaned up, a check should be run to see if any new Markdown\nfiles have been added to ACA-Py in the release. Do that by running the script\n`./scripts/diffMDs.sh`. There are instructions in the output about what to\nexpect to see. If more MD files are listed, add them to both the \"Navigation\"\nsection of the `./scripts/copyFixMDs.sh` script to be listed in an appropriate\nsection of the generated website, and add a `cp` or `sed` command to generate\nthe new document into the documentation.\n\nNext, publish the a local instance of the site and test it. To do so, simply run\n`mkdocs` from the root of the repository. If all goes well, the current set of\ndocs will be published and you will be able to see the documents in your\nbrowser. Look for an errors in the site generation process, particularly missing\nlinks.\n\nWhen all is done, create a PR that merges any updated files into the appropriate\nbranch of this repo. If it is main, merge into the main branch, if not, make sure\nyou change the default target for the pull request merge to be the appropriate branch.\n\n### Fixing Errors\n\nIf there are errors in the building or deploying of the site, make fixes to the\n`\u003cversion\u003e.sh` (and rerun it). A good flow is to run:\n\n`./build-docs.sh -k; mkdocs`\n\nFix an error, Ctrl-C to stop the current serving of the pages and rerun the command.\nThere are live updates on the site as you make changes to the pages, but changes\nto `mkdocs.yml` are not picked up live, and you must restart the server to see those.\n\nRemember as well, that fixing the copy of the docs is **NOT** sufficient--you need\nto make the changes during the copy process from `/tmp` to `/docs` in the `./scripts/copyFixMDs.sh`\nfile, as we will need to run the process over if we change anything fundamental about the\nsite (e.g. the colors, logos, etc.). The content **MUST** remain faithful to the content\nin the ACA-Py repository at the time the version was tagged, but the documentation site\nmay evolve, requiring building the \"per version\" content again from time to time.\n\n#### Adding and Fixing Content\n\nThe basic process for adding content to the site (e.g. a new Markdown file from ACA-Py) is:\n\n- Update the version-specific `nav:` in the `./scripts/copyFixMDs.sh` file.\n- In the `./scripts/copyFixMDs.sh` script, add a command to copy the file from\n  the `/tmp` folder to the appropriate place in the `/docs` folder.\n- If necessary, convert the copy (`cp`) to a `sed` command to update a part of the content\nnecessary. Mostly, such changes are required for relative links to the correct other place in the\nfolder.  The `./scripts/copyFixMDs.sh` file has a number of examples of `sed` conversions:\n  - Documents formerly in the same folder now in another one.\n  - Documents copied from one location (e.g., `GettingStarted...`) into another (e.g., `features`).\n  - Images in other locations.\n  - Relative links to code files to absolute links in the ACA-Py repository.\n  - Fixing multiple things via a pipeline of `sed` commands.\n\n## Checklists for Generating Release Documentation\n\nThe following are checklists for different generation scenarios:\n\n### Updating Main\n\nTo update the documentation for ACA-Py `main` branch:\n\n- Checkout the `main` branch of this repo in your local clone.\n- Update your local clone.\n- Run `./build-docs.sh -t main`\n- Complete a test/fix cycle until you are ready to publish.\n- Create a pull request to the `main` branch of this repo.\n- When the PR is merged, the published site will be automatically updated.\n\n### Adding a New Release\n\nTo add a new release of ACA-Py:\n\n- If the release was produced by tagging the ACA-Py `main` branch, follow the steps above to update the `main` branch of this repo.\n- In GitHub in this repository, create the branch for the new release named for the ACA-Py tag, such as `0.11.0` at the current `main`.\n  - If this is an ACA-Py patch, create the branch in this repo based on the ACA-Py `\u003ctag\u003e` branch (e.g., `0.10.4` from `0.10.3`).\n- Update your local clone to get the new branch.\n- Execute in your local clone `git switch \u003ctag\u003e` to checkout the new branch.\n- Run `./build-docs.sh -t \u003ctag\u003e`\n- Add a file `overrides/main.html` to indicate this is the latest ACA-Py release as described in `overrides/README.doc`\n- Complete a test/fix cycle until you are ready to publish.\n- Create a pull request to the `\u003ctag\u003e` branch of this repo that will be merged into the `\u003ctag\u003e` branch, **NOT** into `main`.\n- Create a new release with the following parameters:\n  - Tag `v\u003ctag\u003e` to be created when published\n  - From `\u003ctag\u003e` branch (**NOT** `main`)\n  - Description: `Documentation for Release \u003ctag\u003e of Aries Cloud Agent Python.`\n  - Check `Latest Release`\n- When the new release is published, the new documentation for the ACA-Py release will be published.\n- Follow the steps to [update a release](#updating-an-existing-release) (below)\nfor the previously current ACA-Py release, to update it's `overrides/main.html`\nfile, as per the guidance in the `overrides/README.doc` -- change the\ntext in the file from indicating its the current release to an older release.\n  - `overrides/main.html` contains the banner text for the publication.\n  - Yes, this step is a pain and kind of stupid. If I had time to do it better I\n    would.\n\n### Updating an Existing Release\n\nTo update the documentation in this repo for an existing release of ACA-Py:\n\n- Update your local clone to get the latest from this repo.\n- If the branch already exists in your local repo, use `git switch \u003ctag\u003e` to checkout the existing branch.\n  - If not, the following will get you a local branch: `git checkout remotes/upstream/\u003ctag\u003e ; git switch -c \u003ctag\u003e`\n- Run `./build-docs.sh -t \u003ctag\u003e`\n- If needed, update the file `overrides/main.html` to indicate this is not the latest ACA-Py release, per the instructions in `overrides/README.doc`\n- Complete a test/fix cycle until you are ready to publish.\n- Create a pull request to the `\u003ctag\u003e` branch of this repo that will be merged into the `\u003ctag\u003e` branch, **NOT** into `main`.\n- Delete the existing release (`v\u003ctag\u003e`), and tag (`v\u003ctag\u003e`) so that the documentation will be republished in the repo.\n  - Creating a new release is the only way (AFAIK) to trigger re-publishing a version other than main.\n- Create a new release with the following parameters:\n  - Tag `v\u003ctag\u003e` to be created when published\n  - From `\u003ctag\u003e` branch (**NOT** `main`)\n  - Description: `Documentation for Release \u003ctag\u003e of Aries Cloud Agent Python.`\n  - Check `Latest Release`\n- When the new release is published, the new documentation for the ACA-Py release will be published.\n\nAs you see mistakes in this documentation, please make updates or create suggestion issues. We really \nneed some GitHub Actions to automate this stuff!\n\n### Removing Published Releases\n\nFrom time to time it is necessary to remove published branches, such as when a final release is completed and you want to \nget rid of the Release Candidate (rc) releases that preceded the release. Here are the steps to do that.\n\n- Checkout the `gh-pages` branch and use git to update it with a `pull`.\n- Checkout the `main` branch of the repo, and update it with a `pull`.\n- Run the command `mike` to delete the branch(es) that you want removed from the public site.\n  - `mike delete -m \"Signed-off-by: Stephen Curran \u003cswcurran@gmail.com\u003e\" -p v0.12.1rc1 v0.12.0rc0 v0.12.0rc2 v0.12.0rc3`\n  - Note that the \"-m\" is the DCO sign-off that is required for all Hyperledger projects. Update the information for what you use for your commits with DCO.\n  - The `mike` command creates a commit on the (by default) `gh-pages` branch, in this case, deleting the unwanted versions of the docs.\n  - The `-p` instructs `mike` to push the update to the `gh-pages` branch.\n_ Checkout the `gh-pages` branch. You should see that your branch is now one commit ahead of the remote (Hyperledger) branch.\n- Push the branch so that you can create a Pull Request. \n- Create a pull request targeting the remote (Hyperledger repository) `gh-pages` branch.\n  - For example, if you use GitHub's `gh` command line utility, the command is `gh pr create -t remove-rc-docs --base gh-pages`\n  - Note the use of `--base gh-pages` to target the pull request to the gh-pages branch.\n- Review and get the pull request approved and merge it.\n- Update your gh-pages branch.\n- Use git to checkout the `main` branch.\n\nDone!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperledger-aries%2Faries-acapy-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperledger-aries%2Faries-acapy-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperledger-aries%2Faries-acapy-docs/lists"}