Migrate documentation hosting to custom domain - #412
Merged
Conversation
The docs were migrated to MkDocs (mkdocs.yml + docs/*.md), but .readthedocs.yaml still configured a Sphinx build pointing at the no-longer-existent docs/conf.py and docs/requirements.txt. That made the RTD build fail, so the root URL redirect to /en/main/ returned a 404. Point Read the Docs at mkdocs.yml, install the package so mkdocstrings can import flask_cors, and add docs/requirements.txt with the MkDocs dependencies. Fixes #403
Scaffold a modern docs site under website/ using Astro Starlight, as an alternative to the MkDocs/Read the Docs setup: - Landing page, getting-started, hand-written API reference for CORS and cross_origin, and example pages ported from the existing docs. - GitHub Actions workflow to build and deploy to GitHub Pages on push to main. Defaults to the project Pages URL; astro.config.mjs documents how to switch to a custom domain. Lives alongside the existing docs/ so nothing is removed yet pending a decision on cutover.
Point the MkDocs site at the custom subdomain: - Add docs/CNAME so the custom domain survives 'mkdocs gh-deploy --force' (which rewrites the gh-pages branch on every release). - Set site_url to https://flask-cors.corydolphin.com so canonical URLs and the sitemap reference the custom domain, deduplicating the old github.io and readthedocs.io copies for SEO. Remove the Astro Starlight scaffold and its Pages workflow: staying on the existing MkDocs + gh-deploy setup (recoverable from history if revisited).
Complete the migration off Read the Docs onto GitHub Pages: - Delete .readthedocs.yaml and docs/requirements.txt. The GitHub Pages deploy (mkdocs gh-deploy) and the check-docs CI job both run via 'uv run mkdocs', pulling the mkdocs toolchain from the dev dependency group in pyproject.toml, so the pip requirements file was redundant duplication kept alive only for RTD's builder. - Repoint the documentation links in README.rst from readthedocs.io to https://flask-cors.corydolphin.com.
Docs previously only deployed via the deploy-docs job in the release workflow, so the published site reflected the last released version and went stale between releases. Move deployment to a deploy-docs job in main.yml that runs on every push to main (gated behind check-docs, never on PRs), and drop the now-redundant deploy-docs job from the release workflow. The docs site now tracks main.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR migrates the Flask-Cors documentation from Read the Docs to a custom domain (
flask-cors.corydolphin.com) hosted via GitHub Pages, with automatic deployment on every push to main.Key Changes
GitHub Pages Deployment: Added a new
deploy-docsjob inmain.ymlthat automatically builds and deploys documentation to GitHub Pages on every push to the main branchcheck-docsjob to prevent deploying broken buildsmkdocs gh-deployfor deploymentRemoved Read the Docs Configuration:
.readthedocs.yamlconfiguration filedeploy-docsjob fromon-release-main.yml(no longer needed for release-based deployments)Custom Domain Setup:
docs/CNAMEfile pointing toflask-cors.corydolphin.commkdocs.ymlto use the custom domain assite_urlDocumentation Links: Updated all documentation links in
README.rstto point to the new custom domain instead of Read the Docs URLsImplementation Details
The new deployment workflow:
gh-pagesbranchhttps://claude.ai/code/session_015oRdhsSvfayv8tPqGkSsqv