Skip to content

Commit 30cc00c

Browse files
committed
Updating Documentation release stratagy
1 parent 810a3ef commit 30cc00c

8 files changed

Lines changed: 543 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Release documentation
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- ".github/workflows/docs.yml"
7+
- "docs/**"
8+
- "scripts/build_release_docs.py"
9+
- "tests/test_release_docs.py"
10+
push:
11+
branches: [main]
12+
paths:
13+
- ".github/workflows/docs.yml"
14+
- "docs/**"
15+
- "scripts/build_release_docs.py"
16+
- "tests/test_release_docs.py"
17+
workflow_dispatch:
18+
inputs:
19+
deploy:
20+
description: "Deploy the validated release site after Pages settings are ready"
21+
type: boolean
22+
default: false
23+
24+
permissions:
25+
contents: read
26+
27+
env:
28+
RELEASE_TAG: v2.2.0
29+
30+
jobs:
31+
build:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Check out documentation tooling
35+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
36+
with:
37+
persist-credentials: false
38+
- name: Check out the released source
39+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
40+
with:
41+
ref: refs/tags/${{ env.RELEASE_TAG }}
42+
path: .docs-release
43+
persist-credentials: false
44+
- name: Set up Python
45+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
46+
with:
47+
python-version: "3.14"
48+
- name: Install documentation dependencies and the released package
49+
run: python -m pip install -r docs/requirements.txt ./.docs-release
50+
- name: Build and validate the versioned site
51+
run: python scripts/build_release_docs.py --source .docs-release --tag "$RELEASE_TAG"
52+
- name: Upload the preview and deployment artifact
53+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
54+
with:
55+
path: docs/_build/site
56+
retention-days: 7
57+
58+
deploy:
59+
if: github.event_name == 'workflow_dispatch' && inputs.deploy && github.ref == 'refs/heads/main'
60+
needs: build
61+
runs-on: ubuntu-latest
62+
permissions:
63+
pages: write
64+
id-token: write
65+
concurrency:
66+
group: release-documentation-pages
67+
cancel-in-progress: false
68+
environment:
69+
name: github-pages
70+
url: ${{ steps.deployment.outputs.page_url }}
71+
steps:
72+
- name: Deploy the versioned site
73+
id: deployment
74+
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -406,6 +406,7 @@ build/
406406
dist/*
407407

408408
# Sphinx
409+
.docs-release/
409410
docs/_build/
410411
docs/_static
411412
docs/_templates

‎README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,45 @@ Feature management provides a way to develop and expose application functionalit
2020

2121
## Contributing
2222

23+
### Release documentation
24+
25+
The [release documentation workflow](https://github.com/microsoft/FeatureManagement-Python/actions/workflows/docs.yml)
26+
builds the verified `v2.2.0` source, not the current `main` API.
27+
The initial release is selected once through the workflow's `RELEASE_TAG` setting.
28+
The builder resolves that tag's commit, derives its version, and checks that the imported package version agrees;
29+
it contains no release-specific version or commit constants.
30+
Pull requests and relevant changes merged into `main` build and validate the site without deploying it.
31+
The downloadable `github-pages` artifact contains the complete site, including `/2.2.0/`, `/latest/`,
32+
and redirects for existing `/html/` links.
33+
34+
To build locally on Windows, use a separate release checkout and virtual environment:
35+
36+
```powershell
37+
git worktree add --detach ..\FeatureManagement-Python-2.2.0 v2.2.0
38+
py -3.14 -m venv ..\FeatureManagement-Python-2.2.0\.venv
39+
& ..\FeatureManagement-Python-2.2.0\.venv\Scripts\Activate.ps1
40+
python -m pip install -r docs\requirements.txt ..\FeatureManagement-Python-2.2.0
41+
python scripts\build_release_docs.py --source ..\FeatureManagement-Python-2.2.0 --tag v2.2.0
42+
Start-Process docs\_build\site\index.html
43+
```
44+
45+
Reuse an existing clean release checkout instead of adding it again.
46+
The builder rejects the wrong commit or tracked release edits, validates local links and API anchors,
47+
and replaces the local site only after a successful build. Generated pages are not committed.
48+
Required API anchors come from methods declared by the tagged feature managers, not a version-independent API list.
49+
Only stable release tags can become `/latest/`; prerelease and development tags are rejected.
50+
Rendering fixes apply only during the build; the historical library source remains unchanged.
51+
SDK documentation follows the [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html).
52+
53+
Deployment is opt-in. After merging this workflow and configuring Pages to use **GitHub Actions**, allow `main`
54+
in the `github-pages` environment. Run **Release documentation** manually from `main` and enable its `deploy` input.
55+
No new secret is required, and PR builds never receive Pages deployment permissions.
56+
Keep `gh-pages` unchanged as a fallback; rollback consists of restoring its `/docs` folder as the Pages source
57+
and allowing `gh-pages` in the deployment environment.
58+
59+
The bootstrap site contains one configured release. Retaining multiple versions, validating older documentation
60+
builds, and registration of future releases are separate follow-up work.
61+
2362
This project welcomes contributions and suggestions. Most contributions require you to agree to a
2463
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
2564
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

‎docs/_sphinx/conf.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# ------------------------------------------------------------------------
2+
# Copyright (c) Microsoft Corporation. All rights reserved.
3+
# Licensed under the MIT License. See License.txt in the project root for
4+
# license information.
5+
# -------------------------------------------------------------------------
6+
"""Shared rendering configuration for tagged release documentation."""
7+
8+
from typing import Any
9+
10+
from sphinx.application import Sphinx
11+
12+
project = "FeatureManagement"
13+
copyright = "2024, Microsoft"
14+
author = "Microsoft"
15+
extensions = [
16+
"myst_parser",
17+
"sphinx.ext.autodoc",
18+
"sphinx.ext.napoleon",
19+
"sphinx_toolbox.more_autodoc.autonamedtuple",
20+
"sphinxcontrib.jquery",
21+
]
22+
html_theme = "sphinx_rtd_theme"
23+
html_static_path: list[str] = []
24+
html_theme_path: list[str] = []
25+
26+
27+
def format_release_docstrings(_app: Sphinx, _what: str, name: str, _obj: Any, _options: Any, lines: list[str]) -> None:
28+
"""Indent historical keyword-field continuations without modifying release source."""
29+
if name not in ("featuremanagement.FeatureManager", "featuremanagement.aio.FeatureManager"):
30+
return
31+
for index, line in enumerate(lines):
32+
if line in ("evaluated.", "context if one isn't provided."):
33+
lines[index] = " " + line
34+
35+
36+
def setup(app: Sphinx) -> dict[str, bool]:
37+
"""Register documentation-only rendering corrections."""
38+
app.connect("autodoc-process-docstring", format_release_docstrings)
39+
return {"parallel_read_safe": True, "parallel_write_safe": True}

‎docs/requirements.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
sphinx==9.2.0
2+
sphinx_rtd_theme==3.1.0
3+
sphinx-toolbox==4.3.1
4+
myst_parser==5.1.0
5+
packaging==26.3

‎project-words.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,29 @@ Aiden
22
APPCONFIGURATION
33
appinsights
44
azuremonitor
5+
buildername
56
caplog
67
Cass
8+
confdir
9+
confoverrides
10+
devrelease
11+
doctreedir
12+
doctrees
713
Entra
814
featurefilters
915
featureflag
1016
featuremanagement
1117
featuremanager
1218
featuremanagerbase
19+
freshenv
20+
gpgsign
21+
outdir
1322
quickstart
1423
rtype
24+
srcdir
25+
statuscode
1526
usefixtures
1627
urandom
28+
venv
29+
warningiserror
30+
worktree

0 commit comments

Comments
 (0)