Skip to content

README.md

Latest commit

 

History

History
79 lines (65 loc) · 4 KB

README.md

File metadata and controls

79 lines (65 loc) · 4 KB
Raw

Course documentation site (Sphinx)

A browsable documentation site generated from the course's own markdown: every module guide, the full mini-book chapters (CI/CD, Django, Containers & Docker), and the fast-track / quiz / dataset guides — with every notebook link pointing at GitHub (one click from there into Colab).

Build

pip install -r docs_site/requirements.txt
cd docs_site
make html
open _build/html/index.html        # Windows: start _build\html\index.html

make html first runs generate.py, which assembles the Sphinx source tree (modules/, extras/, _static/) from the repository's markdown and rewrites relative links so they resolve in the built site. Those directories and _build/ are generated — edit the module READMEs in the repository instead, then rebuild.

Three things generate.py does that are worth knowing when you edit a module:

  • Chapter order follows the README. A mini-book module's sidebar lists its chapters in the order the module README first links to them, not alphabetically. Reorder the README's table of contents and the sidebar follows; add a chapter the README never links to and it still appears, at the end.
  • Links are rewritten by target. Notebooks, scripts and other repo files become GitHub URLs; links to another module's directory or README become that module's page on this site; ../README.md ("🏠 Course home") becomes this site's home page.
  • The sidebar is grouped by hand, and checked. index.md sorts the twenty modules into themed {toctree} blocks ("Python foundations", "Machine learning & applications", …) rather than one 20-entry :glob:, because a flat list of twenty is a wall rather than a table of contents. The cost is that a new module could be left out — so generate.py compares the tree against index.md first and aborts with the offending module's name if they differ.

Beyond the module guides the site also publishes the course-wide pages (fast track, quizzes, datasets) and MAINTENANCE.md as For maintainers — the same quarterly-currency checklist and verification gates contributors run locally. Add another by putting it in EXTRAS in generate.py and giving it a {toctree} entry in index.md.

docs_site/root_files/ is copied verbatim to the site root (html_extra_path). It holds 404.html, which GitHub Pages serves for any unknown path: it is deliberately a standalone file with absolute URLs and inline CSS, because a themed page served from /a/b/c/ cannot resolve its assets by relative path.

make html builds with -W, so an unresolved cross-reference fails the build rather than shipping a dead link — which is the check worth running before you publish. make linkcheck additionally verifies that external URLs still resolve, with localhost URLs and GitHub anchor checks excluded in conf.py since both report working links as broken. Run it before a release and read what it says; external sites go down for reasons that are not your bug, so treat its output as a report rather than a pass/fail gate.

Publishing

The build output is a plain static site — _build/html can be served by GitHub Pages, Read the Docs, or any static host. The site currently lives at https://chrisw09.github.io/Python-for-AI-Driven-Automation/.

There is no CI: publishing is a manual step, so a rebuild only reaches the web when you push it there. The shortest path is to build locally and publish the output to the gh-pages branch:

make -C docs_site html                       # verify it builds clean under -W first
npx gh-pages -d docs_site/_build/html        # or: ghp-import -n -p -f docs_site/_build/html

With GitHub Pages set to serve from the gh-pages branch, that is the whole deployment. (If Pages is still set to the "GitHub Actions" source, switch it to "Deploy from a branch" in the repository's Settings → Pages, or the push will have no effect.) Whichever route you take, build with -W first — a manual publish has no PR to catch a dead link for you.