Google Git
Sign in
chromium/external/github.com/giampaolo/psutil/refs/heads/master/./docs
tree: 87607780d8aa3aa87a207de7a23809ced525a6c5
  1. _ext/
  2. _extra/
  3. _static/
  4. _templates/
  5. blog/
  6. 404.rst
  7. _sponsors.html
  8. about.rst
  9. adoption.rst
  10. alternatives.rst
  11. api-overview.rst
  12. api.rst
  13. blog.rst
  14. changelog.rst
  15. conf.py
  16. credits.rst
  17. devguide.rst
  18. DEVNOTES.md
  19. faq.rst
  20. funding.rst
  21. glossary.rst
  22. index.rst
  23. install.rst
  24. Makefile
  25. migration.rst
  26. performance.rst
  27. platform.rst
  28. README.md
  29. recipes.rst
  30. shell-equivalents.rst
  31. stdlib-equivalents.rst
  32. test_docs.py
  33. test_docs_online.py
  34. testutil.py
  35. timeline.rst
  36. versions.json
docs/README.md

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.
  • versions.json: the version selector's menu (see below).

Notable choices

  • master is served at the site root (no /en/, no /latest/); frozen past releases live under /<version>/, listed in versions.json.
  • 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.

Freezing a doc version

Add an entry to versions.json:

{ "name": "8.0", "url": "/8.0/", "note": "release", "ref": "v8.0.0" }

Entries with a ref are rebuilt from it on every deploy and get an “old version” banner. Nothing is stored, and tags publish nothing on their own. Deleting the entry unpublishes it.

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 -> build past versions -> deploy to GitHub Pages -> live-site tests. Deploy and the live tests run only on push to master, never on PRs.