Metadata-Version: 2.1
Name: canonical-sphinx
Version: 0.7.0
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx>=7.1.2
Requires-Dist: furo
Requires-Dist: myst-parser
Requires-Dist: linkify-it-py
Provides-Extra: full
Requires-Dist: canonical-sphinx-extensions; extra == "full"
Requires-Dist: sphinx-copybutton; extra == "full"
Requires-Dist: sphinx_design; extra == "full"
Requires-Dist: sphinx-notfound-page; extra == "full"
Requires-Dist: sphinx_reredirects; extra == "full"
Requires-Dist: sphinx-tabs; extra == "full"
Requires-Dist: sphinxcontrib-jquery; extra == "full"
Requires-Dist: sphinxext-opengraph; extra == "full"
Requires-Dist: pyspelling; extra == "full"
Requires-Dist: sphinx-autobuild; extra == "full"
Provides-Extra: dev
Requires-Dist: canonical-sphinx[full]; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: coverage[toml]==7.6.1; extra == "dev"
Requires-Dist: pytest==8.3.2; extra == "dev"
Requires-Dist: pytest-cov==5.0.0; extra == "dev"
Requires-Dist: pytest-mock==3.14.0; extra == "dev"
Provides-Extra: lint
Requires-Dist: canonical-sphinx[full]; extra == "lint"
Requires-Dist: black==24.8.0; extra == "lint"
Requires-Dist: codespell[toml]==2.3.0; extra == "lint"
Requires-Dist: ruff==0.6.2; extra == "lint"
Requires-Dist: yamllint==1.35.1; extra == "lint"
Provides-Extra: types
Requires-Dist: canonical-sphinx[full]; extra == "types"
Requires-Dist: mypy[reports]==1.11.2; extra == "types"
Requires-Dist: pyright==1.1.378; extra == "types"
Provides-Extra: docs
Requires-Dist: canonical-sphinx[full]; extra == "docs"
Requires-Dist: sphinx-lint; extra == "docs"

> **This extension is deprecated.**
>
> canonical-sphinx 0.7.0 will be the final major release of this extension. It will
> receive security and bug fixes through the end of the 27.04 release cycle, when
> development will cease entirely.
>
> All Canonical Sphinx projects should now use the Ulwazi theme. Please make the switch at
> your nearest convenience. Guidance is available in [Switch to the Ulwazi
> theme](https://documentation.ubuntu.com/sphinx-stack/latest/how-to/switch-to-ulwazi/).

# canonical-sphinx

Extension and theme to create great Canonical-branded documentation.

## Description

This project is a Sphinx extension that simplifies the installation of a group of Sphinx
extensions recommended by Canonical. It also provides a design override of the Furo
theme for the creation of Canonical-branded documentation.

This extension provides a minimal installation by default, and also offers a `[full]`
optional installation which provides significant additional functionality for
Sphinx-based documentation. This extension, when installed and added to `extensions`
within the configuration file of a Sphinx deployment, bundles various extensions
together and sets default configuration values, eliminating the need to list the
extensions in the `extensions` section of the Sphinx configuration and reducing the need
to configure the bundled extensions.

The default extensions bundled into canonical-sphinx are:

- [Furo](https://github.com/pradyunsg/furo)
- [MyST Parser](https://myst-parser.readthedocs.io/en/latest/)
- [linkify-it-py](https://pypi.org/project/linkify-it-py/) - required for
  specific MyST Parser functionality.

The optional extensions bundled into canonical-sphinx using the `[full]`
optional installation are:

- [canonical-sphinx-extensions](https://github.com/canonical/canonical-sphinx-extensions)
- [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton)
- [sphinx-design](https://github.com/executablebooks/sphinx-design)
- [sphinx-notfound-page](https://github.com/readthedocs/sphinx-notfound-page)
- [sphinx-reredirects](https://github.com/documatt/sphinx-reredirects)
- [sphinx-tabs](https://github.com/executablebooks/sphinx-tabs)
- [sphinxcontrib-jquery](https://github.com/sphinx-contrib/jquery/)
- [sphinxext-opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)
- [pyspelling](https://github.com/facelessuser/pyspelling)

## Using canonical-sphinx

To use canonical-sphinx in your project:

1. Install `canonical-sphinx`.

   This can be done via PyPI, or by using the package available in the
   canonical-sphinx repository.

2. Add `canonical-sphinx` to your [Sphinx configuration
   file](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions).

   For example:

   ```python
   extensions = [
      ...,
      "canonical_sphinx",
   ]
   ```

   **Do not add any of the bundled extensions to this configuration.** They
   will be automatically added when Sphinx generates documentation.

3. (Optional) Add additional configuration to your [Sphinx configuration
   file](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions)
   if you need to overwrite any defaults configured by canonical-sphinx.

### Using a subset of packages

canonical-sphinx will identify and configure defaults for any package from the `[full]`
installation.

For example, using the following `requirements.txt` file:

```text
canonical-sphinx
sphinx-copybutton
sphinxcontrib-jquery
```

With `canonical-sphinx` included in your project's `conf.py` `extensions`:

```python
extensions = [
    "canonical_sphinx",
]
```

Sphinx will configure and add defaults for `sphinx-copybutton` and
`sphinxcontrib-jquery`. The rest of the extensions from the optional `[full]`
installation will be ignored.
