Sphinx Basic NG

1.0.0b2 · active · verified Fri Apr 10

Sphinx Basic NG (sphinx-basic-ng) is a modernised skeleton for Sphinx themes, providing a foundational three-column layout and shared implementations of common components. It aims to simplify Sphinx theme development by offering a consistent vocabulary and a robust base to build upon, serving as an advanced alternative to Sphinx's built-in basic theme. The current version is 1.0.0b2. As a foundational toolkit, its release cadence is likely tied to major Sphinx updates and the evolution of documentation design patterns.

Warnings

breaking As a beta release (1.0.0b2), the API and internal structure of sphinx-basic-ng may not be stable. Expect potential breaking changes in future minor or patch releases before a stable 1.0.0.
Fix: Review changelogs and migration guides for each new release. Pin dependencies to specific versions to manage updates.
gotcha sphinx-basic-ng is a 'skeleton' or 'base' theme, not a fully-fledged, ready-to-use theme. Users are expected to build their own themes on top of it, which requires custom templating, CSS, and potentially JavaScript. Simply activating it will provide a minimal, unstyled foundation.
Fix: Understand that `sphinx-basic-ng` provides components and a layout structure. You will need to write custom CSS/JS and potentially override Jinja2 templates to achieve a complete theme. Refer to its documentation for how to extend and customize.
gotcha Compatibility with specific Sphinx versions is crucial. Past alpha versions explicitly bumped support (e.g., 'Bump up to Sphinx 4'). Incompatible Sphinx versions can lead to build errors or unexpected rendering issues.
Fix: Ensure your project's `conf.py` includes `needs_sphinx = 'X.Y'` where `X.Y` is a Sphinx version known to be compatible with your `sphinx-basic-ng` version. Check the `sphinx-basic-ng` documentation or its `pyproject.toml` for supported Sphinx ranges.
deprecated Internal APIs, like direct access to `_html_page_context`, have been removed in earlier alpha versions. Relying on undocumented internal Sphinx or `sphinx-basic-ng` structures may lead to breakage in updates.
Fix: Avoid relying on underscored (private) attributes or undocumented APIs. Use officially exposed theme options and extension points. If customization requires deeper integration, track the `sphinx-basic-ng` and Sphinx changelogs closely.

Install

pip install sphinx-basic-ng Install latest beta version

Imports

html_theme
```
# in conf.py
html_theme = "sphinx_basic_ng"
```
Sphinx themes are activated by setting the 'html_theme' configuration variable in your project's conf.py file.

Quickstart

After initializing a Sphinx project with `sphinx-quickstart`, modify your `conf.py` file to set `html_theme = 'sphinx_basic_ng'`. You can further customize the theme via `html_theme_options`.

import os
import sys

# Basic Sphinx project setup (run sphinx-quickstart first)
project = 'My Awesome Project'
copyright = '2024, Your Name'
author = 'Your Name'
release = '0.1.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_basic_ng'
html_static_path = ['_static']

# Example of theme options (customize as needed)
html_theme_options = {
    'sidebar_hide_logo': False,
    'light_css_variables': {
        'color-brand-primary': '#6200EE',
        'color-brand-content': '#00B0FF',
    },
    'dark_css_variables': {
        'color-brand-primary': '#BB86FC',
        'color-brand-content': '#00B0FF',
    }
}

view raw JSON →