From 3c4767238905c4ef3c481dafd8343dba695d0b82 Mon Sep 17 00:00:00 2001 From: Karl Johan Grahn <6355577+karl-johan-grahn@users.noreply.github.com> Date: Thu, 14 Nov 2024 19:35:54 +0100 Subject: [PATCH] Update docs to specify latest doc version (#199) --- .github/workflows/closed_pr.yaml | 2 +- .github/workflows/delete_branch.yaml | 4 ++- .github/workflows/pull_request.yaml | 8 ++--- .github/workflows/push.yaml | 4 ++- .github/workflows/release.yaml | 4 +-- README.md | 44 ++++++++++++---------------- theme_common | 2 +- 7 files changed, 33 insertions(+), 35 deletions(-) diff --git a/.github/workflows/closed_pr.yaml b/.github/workflows/closed_pr.yaml index c90213000..51860fcde 100644 --- a/.github/workflows/closed_pr.yaml +++ b/.github/workflows/closed_pr.yaml @@ -7,6 +7,6 @@ on: jobs: push: - uses: stakater/.github/.github/workflows/pull_request_closed.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/pull_request_closed.yaml@v0.0.101 secrets: GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }} diff --git a/.github/workflows/delete_branch.yaml b/.github/workflows/delete_branch.yaml index c622ebae9..a043a6b22 100644 --- a/.github/workflows/delete_branch.yaml +++ b/.github/workflows/delete_branch.yaml @@ -4,6 +4,8 @@ on: delete jobs: delete: - uses: stakater/.github/.github/workflows/branch_deleted.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/branch_deleted.yaml@v0.0.101 + with: + LATEST_DOC_VERSION: "1.0" secrets: GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }} diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml index 494022b0a..dbc84d613 100644 --- a/.github/workflows/pull_request.yaml +++ b/.github/workflows/pull_request.yaml @@ -8,14 +8,14 @@ on: jobs: doc_qa: - uses: stakater/.github/.github/workflows/pull_request_doc_qa.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/pull_request_doc_qa.yaml@v0.0.101 with: MD_CONFIG: .github/md_config.json - DOC_SRC: content + DOC_SRC: content README.md MD_LINT_CONFIG: .markdownlint.yaml build_container: if: ${{ github.base_ref == 'main' }} - uses: stakater/.github/.github/workflows/pull_request_container_build.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/pull_request_container_build.yaml@v0.0.101 with: DOCKER_BUILD_CONTEXTS: content=https://github.com/stakater/mto-docs.git#pull-request-deployments DOCKER_FILE_PATH: Dockerfile @@ -27,6 +27,6 @@ jobs: DOCKER_SECRETS: GIT_AUTH_TOKEN=${{ secrets.PUBLISH_TOKEN }} deploy_doc: - uses: stakater/.github/.github/workflows/pull_request_versioned_doc.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/pull_request_versioned_doc.yaml@v0.0.101 secrets: GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }} diff --git a/.github/workflows/push.yaml b/.github/workflows/push.yaml index f9f22c2de..6f3eca52b 100644 --- a/.github/workflows/push.yaml +++ b/.github/workflows/push.yaml @@ -8,6 +8,8 @@ on: jobs: push: - uses: stakater/.github/.github/workflows/push_versioned_doc.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/push_versioned_doc.yaml@v0.0.101 + with: + LATEST_DOC_VERSION: "1.0" secrets: GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }} diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 1e4a6593c..d9e25b6f6 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -7,11 +7,11 @@ on: jobs: create_release: - uses: stakater/.github/.github/workflows/release_template.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/release_template.yaml@v0.0.101 secrets: SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }} build_container: - uses: stakater/.github/.github/workflows/push_container_only.yaml@v0.0.98 + uses: stakater/.github/.github/workflows/push_container_only.yaml@v0.0.101 with: DOCKER_BUILD_CONTEXTS: content=https://github.com/stakater/mto-docs.git#gh-pages DOCKER_FILE_PATH: Dockerfile diff --git a/README.md b/README.md index fb824187f..2e0d7d807 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,22 @@ # Multi Tenant Operator Documentation -Documentation for [Multi Tenant Operator](https://www.stakater.com/mto) +This repository contains the source for the documentation for [Multi Tenant Operator](https://www.stakater.com/mto). It is built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python. It is also versioned using [mike](https://github.com/jimporter/mike). -SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python. +## Latest doc version + +Before deploying or deleting a version, make sure to specify the correct latest version in the workflow files. + +Make sure the latest doc version is also specified in the versioned branches. ## GitHub Actions -This repository has GitHub action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository. +This repository has [GitHub action workflow](./.github/workflows/) which checks the quality of the documentation and builds the [`Dockerfile`](./Dockerfile) image on Pull Requests. On a push to the `main` branch, it will create a GitHub release and push the built image to an image repository. ## How to make changes -It is important to know that you should only make changes in `theme_override` and `content` directory. Also, be mindful of which `mkdocs.yml` file you change since there are more than one such files. +Fork the repository and make a pull request. + +For MkDocs overrides, it is important to know that you should only make changes in the [`theme_override`](./theme_override/) and the [`content`](./content/) directory. Also, be mindful of only changing the [`theme_override/mkdocs.yml`](./theme_override/mkdocs.yml) file since there are more than one such file. ## Take update on git submodule @@ -20,11 +26,11 @@ This project contains a git submodule and if you wish to take an update on it, y git submodule update --init --recursive --remote ``` -view `.gitmodules` file to see linked git submodules. +View the [`.gitmodules`](./.gitmodules) file to see linked git submodules. ## Build locally -There are at least three options to get fast continuous feedback during local development: +There are at least two options to get fast continuous feedback during local development: 1. Build and run the docs using the Dockerfile image 1. Run the commands locally @@ -59,29 +65,25 @@ Then run below script to prepare theme from local and common theme resources. It ./prepare_theme.sh ``` -Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead: +Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will use `nginx` instead: ```bash -mkdocs serve +mike serve ``` or ```bash -python3 -m mkdocs serve -``` - -if you want to make theme changes with live reload, you can use `--watch-theme` with serve like below: - -```bash -mkdocs serve --watch-theme +python3 -m mike serve ``` -Then, you can make changes in `content` or `dist/_theme` folder. Please note that `dist/_theme` is a build folder and any changes made here will be lost if you do not move them to theme_common or theme_override folder. +Then, you can make changes in `content` or `dist/_theme` folder. Please note that `dist/_theme` is a build folder and any changes made here will be lost if you do not move them to the `theme_common` or the `theme_override` folder. ### QA Checks -Markdown linting: +You can run QA checks locally. They are also run as part of pull request builds. + +To run markdown linting: ```bash brew install markdownlint-cli @@ -95,11 +97,3 @@ brew install vale vale sync vale content ``` - -## Use Tilt - -Install [Tilt](https://docs.tilt.dev/index.html), then run: - -```bash -tilt up -``` diff --git a/theme_common b/theme_common index 0eef29f4c..29c03a469 160000 --- a/theme_common +++ b/theme_common @@ -1 +1 @@ -Subproject commit 0eef29f4cbd2491bbad359c7981501e80e26e78a +Subproject commit 29c03a469af4f812fbc2cedde668e0eb58d1cb02