connected-services-techdocs

The TechDocs for the Connected Services.

About

This is a default README.md file generated by the template. Customize it for your project.

Adding documentation

The homepage of your documentation is in the docs/index.md file. Edit it to suit your usage. Warning: do not delete this file.

Add documentation pages by adding more markdown (.md) files to the docs folder.

Table of contents

The Table of Contents on the right is dynamically generated based on the set of hierarchy of headings in your markdown files. Only use one H1 (# in Markdown) per file.

Site navigation

It is optional, but highly recommended that you define the navigation structure for your documentation by creating a nav section in your mkdocs.yml file. Without a nav section, navigation for your documentation will be dynamically created when viewed within DevHub, but you won't have control over the order in which the pages show and the text will be generated based on the headings in the pages themselves.

Creating a nav section will allow you to completely control how the navigation for your documentation displays in DevHub, including the text that is shown, grouping pages in categories and sub-categories and including links to external content.

We've included some example mkdocs.yml files below which demonstrate how to configure the nav section. You may also wish to consult the MkDocs documentation for detailed information about navigation and other aspects of mkdocs.yml.

nav with categories

Below is an example of a mkdocs.yml file with a nav section. This nav section is structured to arrange the files in categories. In this case the categories are Getting Started and Usage.

site_name: My TechDocs
site_description: Documentation for my project
docs_dir: "docs"
edit_uri: edit/main/docs/
plugins:
    - techdocs-core
    - ezlinks
markdown_extensions:
    - markdown_inline_mermaid
    - md_in_html
    -   mkpatcher:
            location: patcher.py
nav:
- Getting Started:
  - Introduction: index.md
  - Create an account: account.md
  - Setup environment: setup.md
- Usage:
  - Deploy locally: local.md 
  - Deploy to OpenShift: openshift.md

Flat nav

Below is another example of a mkdocs.yml file. It does not use categories to arrange the documentation pages.

site_name: My Techdocs
site_description: Documentation for my project
docs_dir: "docs"
plugins:
    - techdocs-core
    - ezlinks
markdown_extensions:
    - markdown_inline_mermaid
    - md_in_html
    -   mkpatcher:
            location: patcher.py
nav:
    - Introduction: index.md
    - Create an account: account.md
    - Setup environment: setup.md
    - Deploy locally: local.md
    - Deploy to OpenShift: openshift.md

Notes

Note that MkDocs uses mkdocs.yml, not mkdocs.yaml, although both appear to work. Refer to the mkdocs user guide for more details.

Previewing documentation locally

You will likely want to preview your documentation on your computer. Follow these instructions to do so.

Building and publishing your documentation

The publishing workflow builds each TechDocs project in a separate job: getting-started, integration-toolkit, and secure-data-exchange. Each project is published under its own catalog entity name.

Publishing requires access to these GitHub Actions secrets: TECHDOCS_S3_BUCKET_NAME, TECHDOCS_AWS_ACCESS_KEY_ID, TECHDOCS_AWS_SECRET_ACCESS_KEY, TECHDOCS_AWS_REGION, and TECHDOCS_AWS_ENDPOINT. Contact the Developer Experience Team to arrange access and register the root catalog in each DevHub environment.

Branches and review flow

The dev branch is reserved for the APS DevHub POC environment, primarily for custom development such as TechDocs plugins. Point dev at the commit needed for that environment. Updating dev does not automatically publish to S3; the POC's use of that branch is configured separately.

For documentation updates and releases:

1. Create a feature branch from test.
2. Make the changes and open a pull request targeting test. The PR builds and validates all TechDocs projects without publishing.
3. After approval, merge the feature branch into test. Relevant changes automatically publish all projects to DevX DevHub Dev and Test.
4. When ready for a production release, open a pull request from test into main. After approval and merge, relevant changes automatically publish all projects to DevX DevHub Prod and non-production.

The publishing workflow

DevX DevHub Dev and Test share the S3 dev/ prefix. DevX DevHub Prod reads from the bucket root. Their catalog registration lists remain separate. The publishing destination named dev is independent of the Git branch named dev and does not configure the APS DevHub POC.

Trigger	Projects	Publishing destination
Push to test	All	S3 dev/ (DevHub Dev and Test)
Push to main	All	S3 bucket root and dev/
Pull request targeting test or main	All	Build and validate only; no publishing or S3 credentials
Manual run	All or one selected project	Selected destination

Automatic runs are triggered by changes to documentation, catalog files, MkDocs configuration, or the publishing workflow/staging script. The shared DevHub publisher always uploads to dev/ when publishing is enabled; production publishing additionally uploads the same build to the bucket root.

Publishing on demand

1. Open Actions → Build and publish TechDocs → Run workflow.
2. Choose the source branch using GitHub's Use workflow from selector. The selected branch must contain this workflow and the project being published.
3. Select dev for DevHub Dev/Test, or prod for the production bucket root plus dev/. The manual destination takes precedence over the branch: selecting dev on main publishes only to dev/.
4. Select all or one project, then run the workflow. GitHub's choice input supports one selection; repeat the run to publish another individual project.

GitHub exposes manual dispatch once this workflow is present on the repository's default branch.

Adding another TechDocs project

Add the project's catalog to the root catalog-info.yaml, then update the workflow's project dropdown and matrix list, and the allowed project names and catalog cleanup paths in .github/scripts/stage-techdocs.sh.

The staging script copies one project to the root of a disposable Actions checkout and removes nested catalogs so the shared publisher finds exactly one entity. Do not run that script directly in your working checkout.

Getting help or reporting an issue

To report bugs/issues/feature requests, please email the Developer Experience team at Developer.Experience@gov.bc.ca

The full documentation for MkDocs (which is powering the DevHub TechDocs function) is at the MkDocs website. Note that not all content on the site will be applicable to DevHub's use of MkDocs.

Contributing

If you would like to contribute, please see our contributing guidelines.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

© 2024 Province of British Columbia

Refer to the LICENSE file for more information.