sphinx-skos 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sphinx_skos-0.1.0/.gitignore +35 -0
- sphinx_skos-0.1.0/LICENSE +21 -0
- sphinx_skos-0.1.0/PKG-INFO +117 -0
- sphinx_skos-0.1.0/README.md +89 -0
- sphinx_skos-0.1.0/pyproject.toml +81 -0
- sphinx_skos-0.1.0/sphinx_skos/__init__.py +24 -0
- sphinx_skos-0.1.0/sphinx_skos/py.typed +0 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Temporary and binary files
|
|
2
|
+
*~
|
|
3
|
+
*.ruff_cache
|
|
4
|
+
*.mypy_cache
|
|
5
|
+
*.py[cod]
|
|
6
|
+
*.so
|
|
7
|
+
*.cfg
|
|
8
|
+
*.orig
|
|
9
|
+
*.log
|
|
10
|
+
*.pot
|
|
11
|
+
**/__pycache__
|
|
12
|
+
.cache/*
|
|
13
|
+
.*.swp
|
|
14
|
+
|
|
15
|
+
# IDEs and editors
|
|
16
|
+
.vscode
|
|
17
|
+
|
|
18
|
+
# Unittest and coverage
|
|
19
|
+
htmlcov
|
|
20
|
+
.coverage
|
|
21
|
+
.coverage.*
|
|
22
|
+
.tox
|
|
23
|
+
junit*.xml
|
|
24
|
+
coverage.xml
|
|
25
|
+
.pytest_cache/
|
|
26
|
+
|
|
27
|
+
# Environments
|
|
28
|
+
.env
|
|
29
|
+
.venv
|
|
30
|
+
|
|
31
|
+
# Release archives
|
|
32
|
+
dist/
|
|
33
|
+
|
|
34
|
+
# Sphinx build output
|
|
35
|
+
_build/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Samuel Jennings
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: sphinx-skos
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Sphinx extension that builds SKOS vocabularies into a documentation site, one page per concept
|
|
5
|
+
Project-URL: homepage, https://github.com/FAIR-DM/sphinx-skos
|
|
6
|
+
Project-URL: repository, https://github.com/FAIR-DM/sphinx-skos
|
|
7
|
+
Project-URL: documentation, https://github.com/FAIR-DM/sphinx-skos#readme
|
|
8
|
+
Project-URL: changelog, https://github.com/FAIR-DM/sphinx-skos/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Sam <samuel.scott.jennings@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: linked-data,rdf,skos,sphinx,vocabulary
|
|
13
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
14
|
+
Classifier: Framework :: Sphinx
|
|
15
|
+
Classifier: Framework :: Sphinx :: Extension
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: Science/Research
|
|
18
|
+
Classifier: Natural Language :: English
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Documentation
|
|
23
|
+
Classifier: Topic :: Documentation :: Sphinx
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering
|
|
25
|
+
Requires-Python: >=3.12
|
|
26
|
+
Requires-Dist: sphinx>=9.0
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# sphinx-skos
|
|
30
|
+
|
|
31
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/tests.yml)
|
|
32
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/build.yml)
|
|
33
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/publish.yml)
|
|
34
|
+
[](https://codecov.io/gh/FAIR-DM/sphinx-skos)
|
|
35
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
36
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
37
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
38
|
+
[](https://github.com/astral-sh/ruff)
|
|
39
|
+
[](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE)
|
|
40
|
+
|
|
41
|
+
A [Sphinx](https://www.sphinx-doc.org/) extension that builds SKOS vocabularies into a
|
|
42
|
+
documentation site. Point it at your vocabulary files and Sphinx publishes one page for every
|
|
43
|
+
vocabulary, every concept and every collection, with the RDF for each page beside it.
|
|
44
|
+
|
|
45
|
+
## Why
|
|
46
|
+
|
|
47
|
+
A controlled vocabulary is published so that people can read it and machines can resolve it.
|
|
48
|
+
Each concept has a URI, and that URI should lead somewhere useful: a page a person can read, and
|
|
49
|
+
the same concept in RDF for software that asks for it.
|
|
50
|
+
|
|
51
|
+
Most tools that render a SKOS vocabulary produce one long page for the whole vocabulary, or are a
|
|
52
|
+
site generator of their own with their own templates and theming. `sphinx-skos` does neither. It
|
|
53
|
+
turns each concept into an ordinary Sphinx document, so a vocabulary site is a Sphinx site: it can
|
|
54
|
+
hold prose pages next to the generated ones, link between them, and look however its Sphinx theme
|
|
55
|
+
makes it look.
|
|
56
|
+
|
|
57
|
+
## Status
|
|
58
|
+
|
|
59
|
+
Early. The version is `0.0.1`. The package installs and registers with Sphinx, but it does not
|
|
60
|
+
yet read vocabularies or generate pages. The configuration below shows where it is going, not
|
|
61
|
+
what it does today.
|
|
62
|
+
|
|
63
|
+
## Planned usage
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
# conf.py
|
|
67
|
+
extensions = ["sphinx_skos"]
|
|
68
|
+
skos_vocabularies = ["../vocabularies/*.ttl"]
|
|
69
|
+
skos_base_uri = "https://w3id.org/example/vocabularies/"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Built with the `dirhtml` builder, a concept's page lives at its URI with `skos_base_uri` removed,
|
|
73
|
+
so a redirect from the URI's domain to the site maps one address directly onto the other. Each
|
|
74
|
+
page has Turtle, JSON-LD, RDF/XML and N-Triples copies beside it.
|
|
75
|
+
|
|
76
|
+
## Scope & philosophy
|
|
77
|
+
|
|
78
|
+
**What it is.** A Sphinx extension that reads SKOS vocabulary files and turns them into Sphinx
|
|
79
|
+
documents: one page per vocabulary, concept and collection, each with its RDF copies. It works for
|
|
80
|
+
any vocabulary from any organisation.
|
|
81
|
+
|
|
82
|
+
**What it is not.**
|
|
83
|
+
|
|
84
|
+
- **Not a theme.** Logos, colours, fonts and layout come from Sphinx's own theme settings in your
|
|
85
|
+
`conf.py`: `html_theme`, `html_logo`, `html_theme_options` and the rest. The extension renders
|
|
86
|
+
content only. Requests to add a logo, a colour scheme or a layout option to this package will
|
|
87
|
+
be closed with a pointer to [Sphinx's HTML theming
|
|
88
|
+
documentation](https://www.sphinx-doc.org/en/master/usage/theming.html).
|
|
89
|
+
- **Not a vocabulary editor.** The Turtle files are the source. The extension reads them and
|
|
90
|
+
never writes them back.
|
|
91
|
+
- **Not a SKOS validator.** It renders what the files say. Checking a vocabulary's quality is the
|
|
92
|
+
job of tools built for it.
|
|
93
|
+
- **Not a server.** It writes static files. Resolving a URI to a page is done by a redirect
|
|
94
|
+
service such as [w3id.org](https://w3id.org/) or by your web server.
|
|
95
|
+
|
|
96
|
+
**When choices collide:**
|
|
97
|
+
|
|
98
|
+
1. The vocabulary files are the truth. A page shows what they say, and the RDF copies contain
|
|
99
|
+
what they contain, without anything added or dropped.
|
|
100
|
+
2. A concept's address never changes because the extension changed.
|
|
101
|
+
3. Anything a site can set in Sphinx itself stays in Sphinx.
|
|
102
|
+
|
|
103
|
+
### Prior art
|
|
104
|
+
|
|
105
|
+
[pyLODE](https://github.com/RDFLib/pyLODE) renders a SKOS vocabulary or an OWL ontology as HTML
|
|
106
|
+
and is well maintained. It produces a single page per vocabulary, which does not give each concept
|
|
107
|
+
a page of its own to resolve to. `sphinx-skos` exists for the one-page-per-concept case.
|
|
108
|
+
|
|
109
|
+
## Contributing
|
|
110
|
+
|
|
111
|
+
See [CONTRIBUTING.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONTRIBUTING.md). The rules
|
|
112
|
+
every change follows are in
|
|
113
|
+
[CONSTITUTION.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONSTITUTION.md).
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT. See [LICENSE](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE).
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# sphinx-skos
|
|
2
|
+
|
|
3
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/tests.yml)
|
|
4
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/build.yml)
|
|
5
|
+
[](https://github.com/FAIR-DM/sphinx-skos/actions/workflows/publish.yml)
|
|
6
|
+
[](https://codecov.io/gh/FAIR-DM/sphinx-skos)
|
|
7
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
8
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
9
|
+
[](https://pypi.org/project/sphinx-skos/)
|
|
10
|
+
[](https://github.com/astral-sh/ruff)
|
|
11
|
+
[](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE)
|
|
12
|
+
|
|
13
|
+
A [Sphinx](https://www.sphinx-doc.org/) extension that builds SKOS vocabularies into a
|
|
14
|
+
documentation site. Point it at your vocabulary files and Sphinx publishes one page for every
|
|
15
|
+
vocabulary, every concept and every collection, with the RDF for each page beside it.
|
|
16
|
+
|
|
17
|
+
## Why
|
|
18
|
+
|
|
19
|
+
A controlled vocabulary is published so that people can read it and machines can resolve it.
|
|
20
|
+
Each concept has a URI, and that URI should lead somewhere useful: a page a person can read, and
|
|
21
|
+
the same concept in RDF for software that asks for it.
|
|
22
|
+
|
|
23
|
+
Most tools that render a SKOS vocabulary produce one long page for the whole vocabulary, or are a
|
|
24
|
+
site generator of their own with their own templates and theming. `sphinx-skos` does neither. It
|
|
25
|
+
turns each concept into an ordinary Sphinx document, so a vocabulary site is a Sphinx site: it can
|
|
26
|
+
hold prose pages next to the generated ones, link between them, and look however its Sphinx theme
|
|
27
|
+
makes it look.
|
|
28
|
+
|
|
29
|
+
## Status
|
|
30
|
+
|
|
31
|
+
Early. The version is `0.0.1`. The package installs and registers with Sphinx, but it does not
|
|
32
|
+
yet read vocabularies or generate pages. The configuration below shows where it is going, not
|
|
33
|
+
what it does today.
|
|
34
|
+
|
|
35
|
+
## Planned usage
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
# conf.py
|
|
39
|
+
extensions = ["sphinx_skos"]
|
|
40
|
+
skos_vocabularies = ["../vocabularies/*.ttl"]
|
|
41
|
+
skos_base_uri = "https://w3id.org/example/vocabularies/"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Built with the `dirhtml` builder, a concept's page lives at its URI with `skos_base_uri` removed,
|
|
45
|
+
so a redirect from the URI's domain to the site maps one address directly onto the other. Each
|
|
46
|
+
page has Turtle, JSON-LD, RDF/XML and N-Triples copies beside it.
|
|
47
|
+
|
|
48
|
+
## Scope & philosophy
|
|
49
|
+
|
|
50
|
+
**What it is.** A Sphinx extension that reads SKOS vocabulary files and turns them into Sphinx
|
|
51
|
+
documents: one page per vocabulary, concept and collection, each with its RDF copies. It works for
|
|
52
|
+
any vocabulary from any organisation.
|
|
53
|
+
|
|
54
|
+
**What it is not.**
|
|
55
|
+
|
|
56
|
+
- **Not a theme.** Logos, colours, fonts and layout come from Sphinx's own theme settings in your
|
|
57
|
+
`conf.py`: `html_theme`, `html_logo`, `html_theme_options` and the rest. The extension renders
|
|
58
|
+
content only. Requests to add a logo, a colour scheme or a layout option to this package will
|
|
59
|
+
be closed with a pointer to [Sphinx's HTML theming
|
|
60
|
+
documentation](https://www.sphinx-doc.org/en/master/usage/theming.html).
|
|
61
|
+
- **Not a vocabulary editor.** The Turtle files are the source. The extension reads them and
|
|
62
|
+
never writes them back.
|
|
63
|
+
- **Not a SKOS validator.** It renders what the files say. Checking a vocabulary's quality is the
|
|
64
|
+
job of tools built for it.
|
|
65
|
+
- **Not a server.** It writes static files. Resolving a URI to a page is done by a redirect
|
|
66
|
+
service such as [w3id.org](https://w3id.org/) or by your web server.
|
|
67
|
+
|
|
68
|
+
**When choices collide:**
|
|
69
|
+
|
|
70
|
+
1. The vocabulary files are the truth. A page shows what they say, and the RDF copies contain
|
|
71
|
+
what they contain, without anything added or dropped.
|
|
72
|
+
2. A concept's address never changes because the extension changed.
|
|
73
|
+
3. Anything a site can set in Sphinx itself stays in Sphinx.
|
|
74
|
+
|
|
75
|
+
### Prior art
|
|
76
|
+
|
|
77
|
+
[pyLODE](https://github.com/RDFLib/pyLODE) renders a SKOS vocabulary or an OWL ontology as HTML
|
|
78
|
+
and is well maintained. It produces a single page per vocabulary, which does not give each concept
|
|
79
|
+
a page of its own to resolve to. `sphinx-skos` exists for the one-page-per-concept case.
|
|
80
|
+
|
|
81
|
+
## Contributing
|
|
82
|
+
|
|
83
|
+
See [CONTRIBUTING.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONTRIBUTING.md). The rules
|
|
84
|
+
every change follows are in
|
|
85
|
+
[CONSTITUTION.md](https://github.com/FAIR-DM/sphinx-skos/blob/main/CONSTITUTION.md).
|
|
86
|
+
|
|
87
|
+
## License
|
|
88
|
+
|
|
89
|
+
MIT. See [LICENSE](https://github.com/FAIR-DM/sphinx-skos/blob/main/LICENSE).
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "sphinx-skos"
|
|
3
|
+
description = "A Sphinx extension that builds SKOS vocabularies into a documentation site, one page per concept"
|
|
4
|
+
license = "MIT"
|
|
5
|
+
version = "0.1.0"
|
|
6
|
+
readme = "README.md"
|
|
7
|
+
authors = [{ name = "Sam", email = "samuel.scott.jennings@gmail.com" }]
|
|
8
|
+
requires-python = ">=3.12"
|
|
9
|
+
keywords = ["sphinx", "skos", "rdf", "vocabulary", "linked-data"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 2 - Pre-Alpha",
|
|
12
|
+
"Framework :: Sphinx",
|
|
13
|
+
"Framework :: Sphinx :: Extension",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"Intended Audience :: Science/Research",
|
|
16
|
+
"Natural Language :: English",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Programming Language :: Python :: 3.14",
|
|
20
|
+
"Topic :: Documentation",
|
|
21
|
+
"Topic :: Documentation :: Sphinx",
|
|
22
|
+
"Topic :: Scientific/Engineering",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"sphinx>=9.0",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[project.urls]
|
|
29
|
+
homepage = "https://github.com/FAIR-DM/sphinx-skos"
|
|
30
|
+
repository = "https://github.com/FAIR-DM/sphinx-skos"
|
|
31
|
+
documentation = "https://github.com/FAIR-DM/sphinx-skos#readme"
|
|
32
|
+
changelog = "https://github.com/FAIR-DM/sphinx-skos/blob/main/CHANGELOG.md"
|
|
33
|
+
|
|
34
|
+
[dependency-groups]
|
|
35
|
+
dev = [
|
|
36
|
+
"deptry>=0.25.1",
|
|
37
|
+
"mypy>=2.3.1",
|
|
38
|
+
"pre-commit>=4.6.2",
|
|
39
|
+
"pydoclint>=0.10.1",
|
|
40
|
+
"pytest>=9.1.1",
|
|
41
|
+
"pytest-cov>=7.1.0",
|
|
42
|
+
"ruff>=0.15.22",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[build-system]
|
|
46
|
+
requires = ["hatchling"]
|
|
47
|
+
build-backend = "hatchling.build"
|
|
48
|
+
|
|
49
|
+
[tool.hatch.build.targets.wheel]
|
|
50
|
+
packages = ["sphinx_skos"]
|
|
51
|
+
|
|
52
|
+
[tool.hatch.build.targets.sdist]
|
|
53
|
+
include = ["/sphinx_skos", "/README.md", "/LICENSE"]
|
|
54
|
+
|
|
55
|
+
[tool.pytest.ini_options]
|
|
56
|
+
testpaths = ["tests"]
|
|
57
|
+
addopts = ["--strict-markers", "--strict-config", "-ra"]
|
|
58
|
+
|
|
59
|
+
[tool.coverage.run]
|
|
60
|
+
branch = true
|
|
61
|
+
source = ["sphinx_skos"]
|
|
62
|
+
|
|
63
|
+
[tool.coverage.report]
|
|
64
|
+
skip_empty = true
|
|
65
|
+
show_missing = true
|
|
66
|
+
|
|
67
|
+
[tool.ruff]
|
|
68
|
+
extend = "ruff-base.toml"
|
|
69
|
+
|
|
70
|
+
[tool.ruff.lint.extend-per-file-ignores]
|
|
71
|
+
# Asserts are how pytest tests assert.
|
|
72
|
+
"tests/**" = ["S101"]
|
|
73
|
+
|
|
74
|
+
[tool.mypy]
|
|
75
|
+
files = ["sphinx_skos"]
|
|
76
|
+
warn_return_any = true
|
|
77
|
+
warn_unused_ignores = true
|
|
78
|
+
show_error_codes = true
|
|
79
|
+
|
|
80
|
+
[tool.deptry]
|
|
81
|
+
extend_exclude = ["tests/", "docs/"]
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Build SKOS vocabularies into a Sphinx documentation site."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import version
|
|
4
|
+
|
|
5
|
+
from sphinx.application import Sphinx
|
|
6
|
+
from sphinx.util.typing import ExtensionMetadata
|
|
7
|
+
|
|
8
|
+
__version__ = version("sphinx-skos")
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def setup(app: Sphinx) -> ExtensionMetadata:
|
|
12
|
+
"""Register the extension with Sphinx.
|
|
13
|
+
|
|
14
|
+
Args:
|
|
15
|
+
app: The Sphinx application building the site.
|
|
16
|
+
|
|
17
|
+
Returns:
|
|
18
|
+
The extension's version and whether it is safe for parallel builds.
|
|
19
|
+
"""
|
|
20
|
+
return {
|
|
21
|
+
"version": __version__,
|
|
22
|
+
"parallel_read_safe": True,
|
|
23
|
+
"parallel_write_safe": True,
|
|
24
|
+
}
|
|
File without changes
|