Metadata-Version: 2.5
Name: sphinx-skos
Version: 0.5.1
Summary: A Sphinx extension that builds SKOS vocabularies into a documentation site, one page per concept
Project-URL: homepage, https://github.com/FAIR-DM/sphinx-skos
Project-URL: repository, https://github.com/FAIR-DM/sphinx-skos
Project-URL: documentation, https://github.com/FAIR-DM/sphinx-skos#readme
Project-URL: changelog, https://github.com/FAIR-DM/sphinx-skos/blob/main/CHANGELOG.md
Author-email: Sam <samuel.scott.jennings@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: linked-data,rdf,skos,sphinx,vocabulary
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: docutils>=0.21
Requires-Dist: furo>=2025.12.19
Requires-Dist: rdflib>=7.6
Requires-Dist: sphinx>=9.0
Description-Content-Type: text/markdown

# sphinx-skos

[![Tests](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/tests.yml/badge.svg)](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/tests.yml)
[![Build](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/build.yml/badge.svg)](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/build.yml)
[![Publish](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/publish.yml/badge.svg)](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/publish.yml)
[![Coverage](https://codecov.io/gh/FAIR-DM/sphinx-skos/branch/main/graph/badge.svg)](https://codecov.io/gh/FAIR-DM/sphinx-skos)
[![PyPI](https://img.shields.io/pypi/v/sphinx-skos)](https://pypi.org/project/sphinx-skos/)
[![Development status](https://img.shields.io/pypi/status/sphinx-skos)](https://pypi.org/project/sphinx-skos/)
[![Python](https://img.shields.io/pypi/pyversions/sphinx-skos)](https://pypi.org/project/sphinx-skos/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Licence](https://img.shields.io/github/license/FAIR-DM/sphinx-skos)](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE)

A [Sphinx](https://www.sphinx-doc.org/) extension that builds SKOS vocabularies into a
documentation site. Point it at your vocabulary files and Sphinx publishes one page for every
vocabulary, every concept and every collection, with the RDF for each page beside it.

## Why

A controlled vocabulary is published so that people can read it and machines can resolve it.
Each concept has a URI, and that URI should lead somewhere useful: a page a person can read, and
the same concept in RDF for software that asks for it.

Most tools that render a SKOS vocabulary produce one long page for the whole vocabulary, or are a
site generator of their own with their own templates and theming. `sphinx-skos` does neither. It
turns each concept into an ordinary Sphinx document, so a vocabulary site is a Sphinx site: it can
hold prose pages next to the generated ones, link between them, and look however its Sphinx theme
makes it look.

## Status

Early. The package reads your vocabulary files and writes one Sphinx page for every vocabulary,
concept and collection, each with its facts and links, and writes that resource's own RDF beside
it in Turtle, JSON-LD, RDF/XML and N-Triples, named in the page's head with `<link rel="alternate">`
elements. Your own pages can show any resource with the `skos:vocabulary`, `skos:concept` and
`skos:collection` directives.

## Usage

Describe the site in `pyproject.toml`. Keep the vocabulary files outside the `catalogue/`
directory, which holds the generated pages:

```toml
[tool.sphinx-skos]
title = "Example vocabularies"
base-uri = "https://w3id.org/example/vocabularies/"
vocabularies = ["data/*.ttl"]
```

Build the site with one command:

```console
sphinx-skos build
```

The site is written to `_build/site/`, with a front page, a page for every vocabulary, concept and
collection, and Furo as its theme. Add a `docs/` directory for prose pages of your own, or a
`docs/conf.py` to change any setting. A site that already has a `conf.py` can instead list
`sphinx_skos` in its `extensions`, set `skos_vocabularies` and `skos_base_uri`, and build with
`sphinx-build -b dirhtml`.

A concept's page lives at its URI with the base URI removed, so a redirect from the URI's
domain to the site maps one address directly onto the other. See [Publish vocabulary files as a
site](https://github.com/FAIR-DM/sphinx-skos/blob/main/docs/how-to/publish-vocabulary-files.md)
for the steps, [RDF
copies](https://github.com/FAIR-DM/sphinx-skos/blob/main/docs/reference/rdf-copies.md) for the
files written beside each page and
[Settings](https://github.com/FAIR-DM/sphinx-skos/blob/main/docs/reference/settings.md) for what
each setting accepts.

To publish the site to GitHub Pages, call the workflow this repository ships from a job in your
own:

```yaml
jobs:
  site:
    uses: FAIR-DM/sphinx-skos/.github/workflows/build-site.yml@v0.3.2
    permissions:
      contents: read
      pages: write
      id-token: write
```

See [Publish a site to GitHub
Pages](https://github.com/FAIR-DM/sphinx-skos/blob/main/docs/how-to/publish-a-site-to-github-pages.md)
for its inputs and for building pull requests without deploying them.

## Scope & philosophy

**What it is.** A Sphinx extension that reads SKOS vocabulary files and turns them into Sphinx
documents: one page per vocabulary, concept and collection, each with its RDF copies. It works for
any vocabulary from any organisation.

**What it is not.**

- **Not a theme.** Colours, fonts and layout come from Sphinx's own theme settings in your
  `conf.py`: `html_theme`, `html_theme_options` and the rest. The extension adds no
  look-and-feel option. It installs [Furo](https://pradyunsg.me/furo/) and uses it when the site
  sets no theme, so a site looks finished without choosing one. A site's own title and logo can
  be named in the `[tool.sphinx-skos]` table, which passes them to Sphinx's `html_title` and
  `html_logo`, and the repository URL in its `[project.urls]` is linked from Furo's footer. Requests to add a colour scheme or a layout option to this package will be closed
  with a pointer to [Sphinx's HTML theming
  documentation](https://www.sphinx-doc.org/en/master/usage/theming.html).
- **Not a vocabulary editor.** The Turtle files are the source. The extension reads them and
  never writes them back.
- **Not a SKOS validator.** It renders what the files say. Checking a vocabulary's quality is the
  job of tools built for it.
- **Not a server.** It writes static files. Resolving a URI to a page is done by a redirect
  service such as [w3id.org](https://w3id.org/) or by your web server.

**When choices collide:**

1. The vocabulary files are the truth. A page shows what they say, and the RDF copies contain
   what they contain, without anything added or dropped.
2. A concept's address never changes because the extension changed.
3. Anything a site can set in Sphinx itself stays in Sphinx.

### Prior art

[pyLODE](https://github.com/RDFLib/pyLODE) renders a SKOS vocabulary or an OWL ontology as HTML
and is well maintained. It produces a single page per vocabulary, which does not give each concept
a page of its own to resolve to. `sphinx-skos` exists for the one-page-per-concept case.

## Contributing

See [CONTRIBUTING.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONTRIBUTING.md). The rules
every change follows are in
[CONSTITUTION.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONSTITUTION.md).

## License

MIT. See [LICENSE](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE).
