2009scape Sphinx theme

A Sphinx theme that dresses documentation as a 2009-era RuneScape interface. The design language is ported from runescapecn.

Live demo and full documentation →

Install

$ pip install sphinx-2009scape-theme

# docs/conf.py
html_theme = "2009scape"

html_theme_options = {
    "logo_text": "My Project",
    "github_url": "https://github.com/me/my-project",
}

That is the whole setup. The theme registers itself through a Sphinx entry point, so it does not need to be listed in extensions.

What you get

• Layout: sticky header, global-toctree sidebar with client-side collapsing, "on this page" scrollspy column, breadcrumbs, prev/next panels, mobile drawer navigation.
• Content: every docutils and Sphinx node styled: admonitions as interface panels with severity-coded edges, sunken code wells with copy buttons, bevelled tables, gold-edged API signatures, footnotes, glossaries, option lists, figures, search and index pages.
• Fonts: ten RuneScape faces from the CC0-licensed RuneStar/fonts, bundled and served from the build output. No external requests at page load.
• Highlighting: a Pygments style matching runescapecn's code colours (keywords green, attributes and numbers cyan, strings yellow).
• Tokens: every colour, size and bevel is a CSS custom property, so the theme recolours from conf.py without forking a stylesheet.

The theme is dark by design, as the runescapecn registry is. A light palette can be layered on through css_variables.

Options

Full list with defaults in docs/configuration.rst. The ones most projects touch:

Pixel fonts are not ideal for long-form reading, so chrome and body copy can be split and recolouring is a dict of tokens:

html_theme_options = {
    "body_font": "system",      # readable paragraphs
    "heading_font": "rs-bold",  # RuneScape headings and interface labels
    "css_variables": {
        "rs-gold": "#7fd4ff",
        "rs-content-max-width": "52rem",
    },
}

Code blocks always default to a real monospace face; pixel fonts and code indentation do not mix. The token list lives at the top of static/css/2009scape.css.

Development

$ git clone --recurse-submodules https://github.com/arsalan-anwari/2009scape-sphinx-theme
$ cd 2009scape-sphinx-theme
$ uv sync --extra docs --extra test    # .venv with the theme installed editable
$ uv run make -C docs html             # build the demo docs
$ uv run pytest                        # build-level tests

Releases go out through publish.sh, which runs the tests, uploads to PyPI and pushes the built docs to GitHub Pages:

$ ./publish.sh                # tests, PyPI, tag, gh-pages
$ ./publish.sh --docs-only    # just redeploy the docs
$ ./publish.sh --test-pypi    # dry run against TestPyPI

Licence

Theme code is Apache-2.0 (see LICENSE). The bundled RuneScape fonts come from RuneStar/fonts and are CC0-1.0.

Not affiliated with Jagex or RuneScape. A developer tribute, inspired by the game.