Skip to content

Commit

Permalink
ci: add job to check autogenerated docs in tree
Browse files Browse the repository at this point in the history 
Add a job to check that the autogenerated docs in the tree match the
docs that are autogenerated when the docs are built.
  • Loading branch information
@Aflynn50
Aflynn50 committed Jan 15, 2025
1 parent 2f6635a commit 0029444
Show file tree
Hide file tree
Showing 8 changed files with 58 additions and 99 deletions.
14 changes: 13 additions & 1 deletion .github/workflows/context-tests.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ jobs:
check-terraform: ${{ steps.filter-files.outputs.check-terraform }}
check-snap: ${{ steps.filter-files.outputs.check-snap }}
check-generate: ${{ steps.filter-files.outputs.check-generate }}
check-docs: ${{ steps.filter-files.outputs.check-docs }}
steps:
- name: Filter Files
id: filter-files
Expand Down Expand Up @@ -76,6 +77,10 @@ jobs:
- '**.go'
- 'go.mod'
- '.github/workflows/gen.yml'
check-docs:
- '**.go'
- 'go.mod'
- '.github/workflows/docs.yml'
build:
needs: [changed-files]
Expand All @@ -95,6 +100,12 @@ jobs:
if: github.event.pull_request.draft == false && needs.changed-files.outputs.check-generate == 'true'
uses: ./.github/workflows/gen.yml

docs:
needs: [changed-files]
name: Documentation
if: github.event.pull_request.draft == false && needs.changed-files.outputs.check-docs == 'true'
uses: ./.github/workflows/docs.yml

client:
needs: [changed-files]
name: Client Tests
Expand All @@ -121,7 +132,7 @@ jobs:
uses: ./.github/workflows/upgrade.yml

result-check:
needs: [build,snap,generate,client,terraform,migrate,upgrade]
needs: [build,snap,generate,docs,client,terraform,migrate,upgrade]
runs-on: ubuntu-latest
name: Check Tests Passed
if: always() && !cancelled()
Expand All @@ -133,6 +144,7 @@ jobs:
if ${{ needs.build.result == 'success' || needs.build.result == 'skipped' }} \
&& ${{ needs.snap.result == 'success' || needs.snap.result == 'skipped' }} \
&& ${{ needs.generate.result == 'success' || needs.generate.result == 'skipped' }} \
&& ${{ needs.docs.result == 'success' || needs.docs.result == 'skipped' }} \
&& ${{ needs.client.result == 'success' || needs.client.result == 'skipped' }} \
&& ${{ needs.terraform.result != 'fix me' || needs.terraform.result == 'skipped' }} \
&& ${{ needs.migrate.result == 'success' || needs.migrate.result == 'skipped' }} \
Expand Down
104 changes: 43 additions & 61 deletions .github/workflows/docs.yml
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,13 @@
name: "Docs"

on:
push:
branches:
- '3.5'
pull_request:
branches:
- '3.5'
workflow_dispatch:
workflow_call:

jobs:
sync:
name: Sync to Discourse
runs-on: [self-hosted, linux, arm64, aws, large]
env:
TOPIC_IDS: './.github/discourse-topic-ids.yaml'

docs:
name: Check Autogenerated Documentation
runs-on: [linux, self-hosted, x64, large]
steps:
- name: Checkout code
uses: actions/checkout@v4
Expand All @@ -25,56 +18,45 @@ jobs:
go-version-file: 'go.mod'
cache: true

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.10'

- name: Build Juju client
run: |
go install -v -tags minimal ./cmd/juju
- name: Generate CLI docs
id: gen
shell: bash
run: |
# Create temp dir to hold docs
DOCS_DIR=$(mktemp -d)
echo "dir=${DOCS_DIR}" >> $GITHUB_OUTPUT
juju documentation --split --out=$DOCS_DIR --discourse-ids $TOPIC_IDS
# TODO: save $DOCS_DIR as an artifact

- name: Generate controller config keys doc
env:
DOCS_DIR: ${{ steps.gen.outputs.dir }}
JUJU_SRC_ROOT: '.'
run: |
go run ./scripts/md-gen/controller-config
- name: Generate hook tool docs
env:
DOCS_DIR: ${{ steps.gen.outputs.dir }}
run: |
go run ./scripts/md-gen/hook-tools
- name: Add version notice to generated docs
env:
DOCS_DIR: ${{ steps.gen.outputs.dir }}
run: |
go run ./scripts/md-gen/version-notice
- name: pip install requirements
run: |
python3 -m venv .venv
.venv/bin/python3 -m pip install -r ./scripts/discourse-sync/requirements.txt
- name: Check docs on Discourse
if: github.event_name == 'pull_request'
env:
DOCS_DIR: ${{ steps.gen.outputs.dir }}
run: |
.venv/bin/python3 ./scripts/discourse-sync/main.py check
- name: Sync docs to Discourse
if: github.event_name == 'push'
env:
DISCOURSE_API_USERNAME: ${{ secrets.DISCOURSE_API_USERNAME }}
DISCOURSE_API_KEY: ${{ secrets.DISCOURSE_API_KEY }}
DOCS_DIR: ${{ steps.gen.outputs.dir }}
run: |
.venv/bin/python3 ./scripts/discourse-sync/main.py sync
- name: Install sphinx dependencies
run: |
sudo DEBIAN_FRONTEND=noninteractive apt -y update
sudo DEBIAN_FRONTEND=noninteractive apt -y install python3.10-venv
python -m venv venv
source venv/bin/activate
python -m pip install --upgrade --no-cache-dir pip setuptools
python -m pip install --exists-action=w --no-cache-dir -r docs/.sphinx/requirements.txt
- name: Make documentation
run: |
make docs-html
- name: Check for changes
run: |
git add -A
git rm -rf --quiet --cached venv/
if [[ -n $(git diff HEAD) ]]; then
# Print the full diff for debugging purposes
git diff HEAD
echo "*****"
echo "The following generated documentation has been modified:"
git diff --name-status HEAD
echo "Please regenerate these files and check in the changes."
echo ""
echo "When running locally, the CLI documentation is generated by the version of juju on your path, NOT the version in the tree"
echo "To regenerate the documentation locally, install the juju CLI from your local tree and build the docs with:"
echo " go install -v -tags minimal ./cmd/juju"
echo " make docs-html"
echo ""
echo "*****"
exit 1
fi
2 changes: 1 addition & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ tests/tmp.*
*.charm
*.bundle
*.log
dqlite-deps.tar.bz2
dqlite-deps.tar.bz2
1 change: 0 additions & 1 deletion docs/.readthedocs.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ build:
sphinx:
builder: dirhtml
configuration: docs/conf.py
fail_on_warning: true

# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
Expand Down
2 changes: 1 addition & 1 deletion docs/Makefile.sp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ sp-run: sp-install
# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
sp-html: sp-install
. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
. $(VENV); $(SPHINXBUILD) --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
sp-epub: sp-install
. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
Expand Down
18 changes: 0 additions & 18 deletions docs/user/reference/configuration/list-of-model-configuration-keys.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -704,24 +704,6 @@ The maximum size for the action collection, in human-readable memory format.
**Type:** string


## max-status-history-age

The maximum age for status history entries before they are pruned, in human-readable time format.

**Default value:** `336h`

**Type:** string


## max-status-history-size

The maximum size for the status history collection, in human-readable memory format.

**Default value:** `5G`

**Type:** string


## mode

Mode is a comma-separated list which sets the
Expand Down
8 changes: 0 additions & 8 deletions docs/user/reference/juju-cli/list-of-juju-cli-commands/bootstrap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -556,14 +556,6 @@ Model configuration keys (affecting the controller model):
type: string
description: The maximum size for the action collection, in human-readable memory
format
max-status-history-age:
type: string
description: The maximum age for status history entries before they are pruned,
in human-readable time format
max-status-history-size:
type: string
description: The maximum size for the status history collection, in human-readable
memory format
mode:
type: string
description: |-
Expand Down
8 changes: 0 additions & 8 deletions docs/user/reference/juju-cli/list-of-juju-cli-commands/model-config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,14 +234,6 @@ The following keys are available:
type: string
description: The maximum size for the action collection, in human-readable memory
format
max-status-history-age:
type: string
description: The maximum age for status history entries before they are pruned,
in human-readable time format
max-status-history-size:
type: string
description: The maximum size for the status history collection, in human-readable
memory format
mode:
type: string
description: |-
Expand Down

0 comments on commit 0029444

Please sign in to comment.