diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000000..5ed82add33 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,53 @@ +name: publish-docs + +on: + push: + # Publish `main` as latest + branches: + - main + + # Publish `v1.2.3` tags as releases + tags: + - v* + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 # fetch all commits/branches + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - uses: actions/cache@v2 + with: + key: ${{ github.ref }} + path: .cache + - name: Install Python dependencies + run: pip install -r ./mkdocs-requirements.txt + - name: Configure git user + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + - name: Deploy docs + run: | + # Strip git ref prefix from version + echo "${{ github.ref }}" + VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,') + # Strip "v" prefix from tag name + [[ "${{ github.ref }}" == "refs/tags/"* ]] && ALIAS=$(echo $VERSION | sed -e 's/^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 + # Create overrides folder, populate it for version, and then move to not apply if VERSION is main branch + mkdir overrides + echo -e "{% extends "base.html" %}\n\n{% block outdated %}\n You are viewing the documentation for ACA-Py Release $VERSION.\n{% endblock %}" >overrides/base.html + # If building from main, use latest as ALIAS + [ "$VERSION" == "main" ] && ALIAS=latest && mv overrides/base.html overrides/base.txt + echo $VERSION $ALIAS + mike deploy --push --update-aliases $VERSION $ALIAS + mike set-default latest diff --git a/docs/aca-py.org.md b/docs/aca-py.org.md new file mode 100644 index 0000000000..5c6c394712 --- /dev/null +++ b/docs/aca-py.org.md @@ -0,0 +1,29 @@ +# Welcome! + +![Hyperledger Aries](https://raw.githubusercontent.com/hyperledger/aries-acapy-docs/main/assets/Hyperledger_Aries_Logo_Color.png) + +Welcome to the Aries Cloud Agent Python documentation site. On this site you +will find documentation for recent releases of ACA-Py. You'll find a few of the +older versions of ACA-Py (pre-`0.8.0`), all versions since `0.8.0`, and the +`main` branch, which is the latest and greatest. + +All of the documentation here is extracted from the [Aries Cloud Agent Python repository]. +If you want to contribute to the documentation, please start there. + +Ready to go? Scan the tabs in the page header to find the documentation you need now! + +## Code Internals Documentation + +In addition to this documentation site, the ACA-Py community also maintains an +ACA-Py internals documentation site. The internals documentation consists of the +`docstrings` extracted from the ACA-Py Python code and covers all of the +(non-test) modules in the codebase. Check it out on the [Aries Cloud +Agent-Python ReadTheDocs site](https://aries-cloud-agent-python.readthedocs.io/en/latest/). +As with this site, the ReadTheDocs documentation is version specific. + +Got questions? + +- Join us on the [Hyperledger Discord Server](https://chat.hyperledger.org), in the `#aries-cloudagent-python` channel. +- Add an issue in the [Aries Cloud Agent Python repository]. + +[Aries Cloud Agent Python repository]: https://github.com/hyperledger/aries-cloudagent-python diff --git a/docs/assets/aries-favicon.png b/docs/assets/aries-favicon.png new file mode 100644 index 0000000000..5b10050e05 --- /dev/null +++ b/docs/assets/aries-favicon.png @@ -0,0 +1,89 @@ + + + + + + Page not found · GitHub Pages + + + + +
+ +

404

+

File not found

+ +

+ The site configured at this address does not + contain the requested file. +

+ +

+ If this is your site, make sure that the filename case matches the URL + as well as any file permissions.
+ For root URLs (like http://example.com/) you must provide an + index.html file. +

+ +

+ Read the full documentation + for more information about using GitHub Pages. +

+ +
+ GitHub Status — + @githubstatus +
+ + + + +
+ + diff --git a/mkdocs-requirements.txt b/mkdocs-requirements.txt new file mode 100644 index 0000000000..734a4b2c1f --- /dev/null +++ b/mkdocs-requirements.txt @@ -0,0 +1,3 @@ +mkdocs-material +mike +tzdata \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..1c9a9b0667 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,150 @@ +site_name: Hyperledger Aries ACA-Py Docs +repo_name: hyperledger/aries-cloudagent-python +repo_url: https://github.com/hyperledger/aries-cloudagent-python +theme: + name: material + custom_dir: overrides + logo: https://raw.githubusercontent.com/hyperledger/aries-acapy-docs/main/assets/Hyperledger_Aries_Logo_White.png + favicon: https://raw.githubusercontent.com/hyperledger/aries-cloudagent-python/main/docs/assets/aries-favicon.png + icon: + repo: fontawesome/brands/github + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.code.copy + - navigation.expand + - navigation.footer + - navigation.instant + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - toc.follow +# - toc.integrate +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:materialx.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde +plugins: + - search + - mike +extra: + version: + provider: mike +nav: +- Welcome!: + - Welcome: aca-py.org.md + - ACA-Py README: README.md + - Release Notes: CHANGELOG.md +- Features: + - Developer Introduction: features/DevReadMe.md + - DevContainer Support: features/devcontainer.md + - Supported Aries Interop Profiles and RFCs: features/SupportedRFCs.md + - The Admin API: features/AdminAPI.md + - ACA-Py Plugins: features/PlugIns.md + - Multitenant ACA-Py: features/Multitenancy.md + - DID Methods: features/DIDMethods.md + - DID Resolution: features/DIDResolution.md + - Configuring Multiple Indy Ledgers: features/Multiledger.md + - Automatically Endorsing Indy Transations: features/Endorser.md + - Using W3C JSON-LD Signed Credentials: features/JsonLdCredentials.md + - Using SD-JWTs: features/SelectiveDisclosureJWTs.md + - AnonCreds Presentation Validation: features/AnoncredsProofValidation.md + - Multiple Credential Types: features/Multicredentials.md + - Code Generation with the Open API: features/UsingOpenAPI.md + - ACA-Py as a DIDComm Mediator: features/Mediation.md +- Demos: + - The Alice-Faber Demo: demo/README.md + - Open API Tutorial: demo/AriesOpenAPIDemo.md + - Alice Gets a Phone: demo/AliceGetsAPhone.md + - Hyperledger Indy Endorser In Action: demo/Endorser.md + - Using W3C JSON-LD Credentials: demo/AliceWantsAJsonCredential.md + - DIY -- ACME Controller Workshop: demo/AcmeDemoWorkshop.md + - Aries Using Postman Demo: demo/AriesPostmanDemo.md +- Getting Started: + - Becoming an Indy/Aries Developer: gettingStarted/README.md + - Hyperledger Indy Basics: gettingStarted/IndyBasics.md + - Hyperledger Aries Basics: gettingStarted/AriesBasics.md + - Decentralized Identity Demos: gettingStarted/DecentralizedIdentityDemos.md + - Aries - The Big Picture: gettingStarted/AriesBigPicture.md + - Aries Architecture: gettingStarted/AriesAgentArchitecture.md + - Aries Messaging: gettingStarted/AriesMessaging.md + - Aries Developer Demos: gettingStarted/AriesDeveloperDemos.md + - Agent Connections: gettingStarted/AgentConnections.md + - Issuing AnonCreds Credentials: gettingStarted/IssuingAnonCredsCredentials.md + - Presenting AnonCreds Proofs: gettingStarted/PresentingAnonCredsProofs.md + - Making Your Own ACA-Py Agent: gettingStarted/YourOwnAriesAgent.md + - Aries Developer Options: gettingStarted/IndyAriesDevOptions.md + - DIDComm Messaging: gettingStarted/DIDcommMsgs.md + - DIDComm Message Routing: gettingStarted/RoutingEncryption.md + - DIDComm Message Routing Example: gettingStarted/AriesRoutingExample.md + - TODO Connecting to an Indy Network: gettingStarted/ConnectIndyNetwork.md + - AnonCreds Credential Revocation: gettingStarted/CredentialRevocation.md +- Deploying: + - Deployment Model: deploying/deploymentModel.md + - Upgrading ACA-Py: deploying/UpgradingACA-Py.md + - Indy SDK to Askar Migration: deploying/IndySDKtoAskarMigration.md + - The Use of Poetry in ACA-Py: deploying/Poetry.md + - ACA-Py Container Images: deploying/ContainerImagesAndGithubActions.md + - Databases: deploying/Databases.md + - Persistent Queues and Caching: deploying/RedisPlugins.md + - The askar-anoncreds Wallet Type: deploying/AnonCredsWalletType.md +- Testing/Troubleshooting: + - Running and Creating Unit Tests: testing/UnitTests.md + - Managing Logging: testing/Logging.md + - ACA-Py Integration Tests: testing/INTEGRATION-TESTS.md + - Protocol Tracing: testing/AgentTracing.md + - Troubleshooting: testing/Troubleshooting.md +- Contributing: + - How to Contribute: CONTRIBUTING.md + - Maintainers: MAINTAINERS.md + - Hyperledger Code of Conduct: CODE_OF_CONDUCT.md + - Security Vulnerability Reporting: SECURITY.md + - Publishing an ACA-Py Release: PUBLISHING.md + - Updating the ACA-Py ReadTheDocs Site: UpdateRTD.md