Skip to content

Commit b063c76

Browse files
JulianJulian
committed
Add a small doc setup with just an example.
1 parent 4e457a5 commit b063c76

File tree

9 files changed

+411
-1
lines changed

9 files changed

+411
-1
lines changed

‎.github/workflows/ci.yml

+10
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,16 @@ jobs:
5454
toxenv: py310-safety
5555
- name: "3.10"
5656
toxenv: py310-tests
57+
- name: "3.10"
58+
toxenv: docs-dirhtml
59+
- name: "3.10"
60+
toxenv: docs-doctest
61+
- name: "3.10"
62+
toxenv: docs-linkcheck
63+
- name: "3.10"
64+
toxenv: docs-spelling
65+
- name: "3.10"
66+
toxenv: docs-style
5767
- name: "3.10"
5868
toxenv: readme
5969
- name: "3.10"

‎.readthedocs.yml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
version: 2
2+
3+
sphinx:
4+
builder: dirhtml
5+
configuration: docs/conf.py
6+
fail_on_warning: true
7+
8+
formats: all
9+
10+
python:
11+
version: "3.8"
12+
install:
13+
- requirements: docs/requirements.txt
14+
- method: pip
15+
path: .

‎docs/Makefile

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py

+234
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/master/config
8+
9+
import importlib.metadata
10+
import re
11+
12+
# -- Project information -----------------------------------------------------
13+
14+
project = "sphinx-json-schema-spec"
15+
author = "Julian Berman"
16+
copyright = "2013, " + author
17+
18+
# version: The short X.Y version
19+
# release: The full version, including alpha/beta/rc tags.
20+
release = importlib.metadata.version("sphinx_json_schema_spec")
21+
version = release.partition("-")[0]
22+
23+
24+
# -- General configuration ---------------------------------------------------
25+
26+
# If your documentation needs a minimal Sphinx version, state it here.
27+
#
28+
# needs_sphinx = "1.0"
29+
30+
default_role = "any"
31+
32+
primary_domain = "rst"
33+
34+
# Add any Sphinx extension module names here, as strings. They can be
35+
# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
36+
# ones.
37+
extensions = [
38+
"sphinx.ext.autodoc",
39+
"sphinx.ext.autosectionlabel",
40+
"sphinx.ext.coverage",
41+
"sphinx.ext.doctest",
42+
"sphinx.ext.intersphinx",
43+
"sphinx.ext.napoleon",
44+
"sphinx.ext.todo",
45+
"sphinx_json_schema_spec",
46+
"sphinxcontrib.spelling",
47+
]
48+
49+
# Add any paths that contain templates here, relative to this directory.
50+
templates_path = ["_templates"]
51+
52+
# The suffix(es) of source filenames.
53+
# You can specify multiple suffix as a list of string:
54+
#
55+
# source_suffix = [".rst", ".md"]
56+
source_suffix = ".rst"
57+
58+
# The master toctree document.
59+
master_doc = "index"
60+
61+
# The language for content autogenerated by Sphinx. Refer to documentation
62+
# for a list of supported languages.
63+
#
64+
# This is also used if you do content translation via gettext catalogs.
65+
# Usually you set "language" from the command line for these cases.
66+
language = "en"
67+
68+
# List of patterns, relative to source directory, that match files and
69+
# directories to ignore when looking for source files.
70+
# This pattern also affects html_static_path and html_extra_path.
71+
exclude_patterns = [u"_build", "Thumbs.db", ".DS_Store"]
72+
73+
# The name of the Pygments (syntax highlighting) style to use.
74+
pygments_style = "sphinx"
75+
76+
77+
# -- Options for HTML output -------------------------------------------------
78+
79+
# The theme to use for HTML and HTML Help pages. See the documentation for
80+
# a list of builtin themes.
81+
#
82+
html_theme = "furo"
83+
84+
# Theme options are theme-specific and customize the look and feel of a theme
85+
# further. For a list of options available for each theme, see the
86+
# documentation.
87+
#
88+
# html_theme_options = {}
89+
90+
# Add any paths that contain custom static files (such as style sheets) here,
91+
# relative to this directory. They are copied after the builtin static files,
92+
# so a file named "default.css" will overwrite the builtin "default.css".
93+
# html_static_path = ["_static"]
94+
95+
# Custom sidebar templates, must be a dictionary that maps document names
96+
# to template names.
97+
#
98+
# The default sidebars (for documents that don't match any pattern) are
99+
# defined by theme itself. Builtin themes are using these templates by
100+
# default: ``["localtoc.html", "relations.html", "sourcelink.html",
101+
# "searchbox.html"]``.
102+
#
103+
# html_sidebars = {}
104+
105+
106+
# -- Options for HTMLHelp output ---------------------------------------------
107+
108+
# Output file base name for HTML help builder.
109+
htmlhelp_basename = "sphinxjsonschemaspecdoc"
110+
111+
112+
# -- Options for LaTeX output ------------------------------------------------
113+
114+
latex_elements = {
115+
# The paper size ("letterpaper" or "a4paper").
116+
#
117+
# "papersize": "letterpaper",
118+
119+
# The font size ("10pt", "11pt" or "12pt").
120+
#
121+
# "pointsize": "10pt",
122+
123+
# Additional stuff for the LaTeX preamble.
124+
#
125+
# "preamble": "",
126+
127+
# Latex figure (float) alignment
128+
#
129+
# "figure_align": "htbp",
130+
}
131+
132+
# Grouping the document tree into LaTeX files. List of tuples
133+
# (source start file, target name, title,
134+
# author, documentclass [howto, manual, or own class]).
135+
latex_documents = [
136+
(
137+
master_doc,
138+
"Sphinx JSON Schema Spec.tex",
139+
project,
140+
author,
141+
"manual",
142+
),
143+
]
144+
145+
146+
# -- Options for manual page output ------------------------------------------
147+
148+
# One entry per manual page. List of tuples
149+
# (source start file, name, description, authors, manual section).
150+
man_pages = [
151+
(
152+
master_doc,
153+
project,
154+
project,
155+
[author],
156+
1,
157+
),
158+
]
159+
160+
161+
# -- Options for Texinfo output ----------------------------------------------
162+
163+
# Grouping the document tree into Texinfo files. List of tuples
164+
# (source start file, target name, title, author,
165+
# dir menu entry, description, category)
166+
texinfo_documents = [
167+
(
168+
master_doc,
169+
project,
170+
project,
171+
author,
172+
project,
173+
"",
174+
"Miscellaneous",
175+
),
176+
]
177+
178+
179+
# -- Options for Epub output -------------------------------------------------
180+
181+
# Bibliographic Dublin Core info.
182+
epub_title = project
183+
184+
# The unique identifier of the text. This can be a ISBN number
185+
# or the project homepage.
186+
#
187+
# epub_identifier = ""
188+
189+
# A unique identification for the text.
190+
#
191+
# epub_uid = ""
192+
193+
# A list of files that should not be packed into the epub file.
194+
epub_exclude_files = ["search.html"]
195+
196+
197+
# -- Extension configuration -------------------------------------------------
198+
199+
# -- Options for autodoc extension -------------------------------------------
200+
201+
autodoc_default_options = {
202+
"members": True,
203+
"member-order": "bysource",
204+
}
205+
206+
# -- Options for autosectionlabel extension ----------------------------------
207+
208+
autosectionlabel_prefix_document = True
209+
210+
# -- Options for intersphinx extension ---------------------------------------
211+
212+
# Example configuration for intersphinx: refer to the Python standard library.
213+
intersphinx_mapping = {
214+
"jsonschema": (
215+
"https://python-jsonschema.readthedocs.io/en/latest/", None,
216+
),
217+
"packaging": ("https://packaging.python.org/", None),
218+
"python": ("https://docs.python.org/", None),
219+
"sphinx": ("https://www.sphinx-doc.org/en/master/", None),
220+
}
221+
222+
# -- Options for the linkcheck builder ------------------------------------
223+
224+
225+
def entire_domain(host):
226+
return r"http.?://" + re.escape(host) + r"($|/.*)"
227+
228+
229+
linkcheck_ignore = [
230+
entire_domain("codecov.io"),
231+
entire_domain("img.shields.io"),
232+
"https://github.com/python-jsonschema/sphinx-json-schema-spec/actions",
233+
"https://github.com/python-jsonschema/sphinx-json-schema-spec/workflows/CI/badge.svg", # noqa: E501
234+
]

‎docs/index.rst

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. _sphinx_json_schema_spec:
2+
3+
.. include:: ../README.rst
4+
5+
Usage
6+
-----
7+
8+
The extension currently provides a single Sphinx `role`:
9+
10+
.. role:: kw
11+
12+
Link to the current JSON Schema specification's definition of the keyword
13+
provided.
14+
15+
For instance, writing:
16+
17+
.. code-block:: rst
18+
19+
Reference resolution in JSON Schema is done using the :kw:`$ref` keyword.
20+
21+
will produce:
22+
23+
Reference resolution in JSON Schema is done using the :kw:`$ref` keyword.
24+
25+
What's here, albeit crude, has been used in some form for a long while by `jsonschema` (the Python library), but the hope is it may be useful to alternate implementations or users in general.
26+
Help is very much welcome to improve it!
27+
28+
In the future support may be added for linking to different drafts, or for linking to `Understanding JSON Schema <https://json-schema.org/understanding-json-schema/index.html>`_.

‎docs/requirements.in

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
file:.#egg=sphinx_json_schema_spec
2+
furo
3+
sphinx>=5.1
4+
sphinxcontrib-spelling>5

‎docs/requirements.txt

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#
2+
# This file is autogenerated by pip-compile with python 3.10
3+
# To update, run:
4+
#
5+
# pip-compile docs/requirements.in
6+
#
7+
alabaster==0.7.12
8+
# via sphinx
9+
babel==2.10.3
10+
# via sphinx
11+
beautifulsoup4==4.11.1
12+
# via furo
13+
certifi==2022.6.15
14+
# via requests
15+
charset-normalizer==2.1.0
16+
# via requests
17+
docutils==0.19
18+
# via sphinx
19+
furo==2022.6.21
20+
# via -r docs/requirements.in
21+
idna==3.3
22+
# via requests
23+
imagesize==1.4.1
24+
# via sphinx
25+
jinja2==3.1.2
26+
# via sphinx
27+
lxml==4.9.1
28+
# via sphinx-json-schema-spec
29+
markupsafe==2.1.1
30+
# via jinja2
31+
packaging==21.3
32+
# via sphinx
33+
pyenchant==3.2.2
34+
# via sphinxcontrib-spelling
35+
pygments==2.13.0
36+
# via
37+
# furo
38+
# sphinx
39+
pyparsing==3.0.9
40+
# via packaging
41+
pytz==2022.2.1
42+
# via babel
43+
requests==2.28.1
44+
# via sphinx
45+
snowballstemmer==2.2.0
46+
# via sphinx
47+
soupsieve==2.3.2.post1
48+
# via beautifulsoup4
49+
sphinx==5.1.1
50+
# via
51+
# -r docs/requirements.in
52+
# furo
53+
# sphinx-basic-ng
54+
# sphinx-json-schema-spec
55+
# sphinxcontrib-spelling
56+
sphinx-basic-ng==0.0.1a12
57+
# via furo
58+
file:.#egg=sphinx_json_schema_spec
59+
# via -r docs/requirements.in
60+
sphinxcontrib-applehelp==1.0.2
61+
# via sphinx
62+
sphinxcontrib-devhelp==1.0.2
63+
# via sphinx
64+
sphinxcontrib-htmlhelp==2.0.0
65+
# via sphinx
66+
sphinxcontrib-jsmath==1.0.1
67+
# via sphinx
68+
sphinxcontrib-qthelp==1.0.3
69+
# via sphinx
70+
sphinxcontrib-serializinghtml==1.1.5
71+
# via sphinx
72+
sphinxcontrib-spelling==7.6.0
73+
# via -r docs/requirements.in
74+
urllib3==1.26.11
75+
# via requests

‎docs/spelling_wordlist.txt

Whitespace-only changes.

0 commit comments

Comments
 (0)