| # psutil documentation |
| |
| This directory is a self-contained Sphinx project that builds the psutil docs |
| published at https://psutil.io/. It has grown well past a plain API reference |
| (custom theme, a blog, social cards, its own test suite and deploy pipeline), |
| so this file is the map. |
| |
| ## Build & preview |
| |
| make html # one-off build into _build/html |
| make autoreload # live-reload server at 127.0.0.1:8000 |
| |
| `make html` turns warnings into errors, same as CI. |
| |
| ## Layout |
| |
| - `*.rst`: the doc sources. `api.rst` is the hand-written API reference; |
| `index.rst` is the home page. |
| - `blog/`: blog posts, managed by the ablog extension + comments provided via |
| giscus. |
| - `conf.py`: Sphinx config: extensions, the theme, `html_baseurl`, OpenGraph / |
| sitemap / feed settings. |
| - `_templates/`: the custom theme, built on Sphinx's `basic` theme (topbar, |
| sidebar, footer, layout). |
| - `_static/css/`, `_static/js/`: styles and vanilla JS (no framework). |
| - `_ext/`: small local Sphinx extensions. |
| - `_extra/robots.txt`: copied verbatim to the site root. |
| |
| ## Notable choices |
| |
| - Single version, served at the site root (no `/en/`, no `/latest/`). |
| - Built with the `dirhtml` builder, so URLs are extensionless directories |
| (`psutil.io/faq/`, no `.html`). |
| - Self-hosted on GitHub Pages under the custom domain psutil.io. |
| - Fonts, CSS and JS are all self-hosted; no external assets. |
| - Social cards, sitemap and Atom feed are generated at build time and rooted at |
| `html_baseurl`. |
| |
| ## Tests |
| |
| - `test_docs.py`: offline checks on the built HTML (canonical / OG tags, |
| sitemap, feed, blog metadata, no external assets, ...). Run with `make test`. |
| - `test_docs_online.py`: smoke tests against the live site (reachability, |
| http->https, 404 page, metadata). Run with `make test-online-doc` (sets |
| `PSUTIL_DOCS_ONLINE=1`). |
| |
| ## Deploy |
| |
| `.github/workflows/docs.yml` runs on pushes / PRs that touch `docs/`: lint |
| (`make lint-rst`) -> offline tests -> build -> deploy to GitHub Pages -> |
| live-site tests. Deploy and the live tests run only on push to master, never on |
| PRs. |
