Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
name: Release documentation

on:
pull_request:
paths:
- ".github/workflows/docs.yml"
- "docs/**"
- "scripts/build_release_docs.py"
- "tests/test_release_docs.py"
push:
branches: [main]
paths:
- ".github/workflows/docs.yml"
- "docs/**"
- "scripts/build_release_docs.py"
- "tests/test_release_docs.py"
workflow_dispatch:
inputs:
deploy:
description: "Deploy the validated release site after Pages settings are ready"
type: boolean
default: false

permissions:
contents: read

env:
RELEASE_TAG: v2.2.0

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out documentation tooling
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Check out the released source
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: refs/tags/${{ env.RELEASE_TAG }}
path: .docs-release
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.14"
- name: Install documentation dependencies and the released package
run: python -m pip install -r docs/requirements.txt ./.docs-release
- name: Build and validate the versioned site
run: python scripts/build_release_docs.py --source .docs-release --tag "$RELEASE_TAG"
- name: Upload the preview and deployment artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: docs/_build/site
retention-days: 7

deploy:
if: github.event_name == 'workflow_dispatch' && inputs.deploy && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
concurrency:
group: release-documentation-pages
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy the versioned site
id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -406,6 +406,7 @@ build/
dist/*

# Sphinx
.docs-release/
docs/_build/
docs/_static
docs/_templates
Expand Down
39 changes: 39 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,45 @@ Feature management provides a way to develop and expose application functionalit

## Contributing

### Release documentation

The [release documentation workflow](https://github.com/microsoft/FeatureManagement-Python/actions/workflows/docs.yml)
builds the verified `v2.2.0` source, not the current `main` API.
The initial release is selected once through the workflow's `RELEASE_TAG` setting.
The builder resolves that tag's commit, derives its version, and checks that the imported package version agrees;
it contains no release-specific version or commit constants.
Pull requests and relevant changes merged into `main` build and validate the site without deploying it.
The downloadable `github-pages` artifact contains the complete site, including `/2.2.0/`, `/latest/`,
and redirects for existing `/html/` links.

To build locally on Windows, use a separate release checkout and virtual environment:

```powershell
git worktree add --detach ..\FeatureManagement-Python-2.2.0 v2.2.0
py -3.14 -m venv ..\FeatureManagement-Python-2.2.0\.venv
& ..\FeatureManagement-Python-2.2.0\.venv\Scripts\Activate.ps1
python -m pip install -r docs\requirements.txt ..\FeatureManagement-Python-2.2.0
python scripts\build_release_docs.py --source ..\FeatureManagement-Python-2.2.0 --tag v2.2.0
Start-Process docs\_build\site\index.html
```

Reuse an existing clean release checkout instead of adding it again.
The builder rejects the wrong commit or tracked release edits, validates local links and API anchors,
and replaces the local site only after a successful build. Generated pages are not committed.
Required API anchors come from methods declared by the tagged feature managers, not a version-independent API list.
Only stable release tags can become `/latest/`; prerelease and development tags are rejected.
Rendering fixes apply only during the build; the historical library source remains unchanged.
SDK documentation follows the [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html).

Deployment is opt-in. After merging this workflow and configuring Pages to use **GitHub Actions**, allow `main`
in the `github-pages` environment. Run **Release documentation** manually from `main` and enable its `deploy` input.
No new secret is required, and PR builds never receive Pages deployment permissions.
Keep `gh-pages` unchanged as a fallback; rollback consists of restoring its `/docs` folder as the Pages source
and allowing `gh-pages` in the deployment environment.

The bootstrap site contains one configured release. Retaining multiple versions, validating older documentation
builds, and registration of future releases are separate follow-up work.

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
Expand Down
39 changes: 39 additions & 0 deletions docs/_sphinx/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# ------------------------------------------------------------------------
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License. See License.txt in the project root for
# license information.
# -------------------------------------------------------------------------
"""Shared rendering configuration for tagged release documentation."""

from typing import Any

from sphinx.application import Sphinx

project = "FeatureManagement"
copyright = "2024, Microsoft"
author = "Microsoft"
extensions = [
"myst_parser",
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx_toolbox.more_autodoc.autonamedtuple",
"sphinxcontrib.jquery",
]
html_theme = "sphinx_rtd_theme"
html_static_path: list[str] = []
html_theme_path: list[str] = []


def format_release_docstrings(_app: Sphinx, _what: str, name: str, _obj: Any, _options: Any, lines: list[str]) -> None:
"""Indent historical keyword-field continuations without modifying release source."""
if name not in ("featuremanagement.FeatureManager", "featuremanagement.aio.FeatureManager"):
return
for index, line in enumerate(lines):
if line in ("evaluated.", "context if one isn't provided."):
lines[index] = " " + line


def setup(app: Sphinx) -> dict[str, bool]:
"""Register documentation-only rendering corrections."""
app.connect("autodoc-process-docstring", format_release_docstrings)
return {"parallel_read_safe": True, "parallel_write_safe": True}
5 changes: 5 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
sphinx==9.2.0
sphinx_rtd_theme==3.1.0
sphinx-toolbox==4.3.1
myst_parser==5.1.0
packaging==26.3
14 changes: 14 additions & 0 deletions project-words.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,29 @@ Aiden
APPCONFIGURATION
appinsights
azuremonitor
buildername
caplog
Cass
confdir
confoverrides
devrelease
doctreedir
doctrees
Entra
featurefilters
featureflag
featuremanagement
featuremanager
featuremanagerbase
freshenv
gpgsign
outdir
quickstart
rtype
srcdir
statuscode
usefixtures
urandom
venv
warningiserror
worktree
Loading
Loading