Skip to content

Commit 36656ec

Browse files
ianthomas23ianthomas23
committed
Doc build
1 parent a9805b6 commit 36656ec

File tree

6 files changed

+242
-0
lines changed

6 files changed

+242
-0
lines changed

‎docs/Makefile‎

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

‎docs/conf.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'jupyter-schemas'
10+
copyright = '2024, .'
11+
author = 'Jupyter Development Team'
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = [
17+
'sphinx.ext.autodoc',
18+
'sphinx_design',
19+
'sphinx-jsonschema'
20+
]
21+
22+
templates_path = ['_templates']
23+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
24+
25+
26+
27+
# -- Options for HTML output -------------------------------------------------
28+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
29+
30+
html_theme = 'pydata_sphinx_theme'
31+
html_static_path = ['_static']

‎docs/example.rst‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
Example schema
2+
==============
3+
4+
.. tab-set::
5+
6+
.. tab-item:: Rendered using sphinx-jsonschema
7+
8+
.. jsonschema:: ../schema/server/events/kernel-actions/v1/kernel-actions.schema.json
9+
10+
.. tab-item:: JSON
11+
12+
.. literalinclude:: ../schema/server/events/kernel-actions/v1/kernel-actions.schema.json
13+
:language: JSON
14+
15+
.. tab-item:: TOML
16+
17+
.. code-block:: toml
18+
19+
"$schema" = "https://json-schema.org/draft/2020-12/schema"
20+
"$id" = "https://schema.jupyter.org/server/events/kernel-actions/v1/kernel-actions.schema.json"
21+
version = 1
22+
title = "Kernel Manager activities"
23+
personal-data = true
24+
description = "Record events of a kernel manager.\n"
25+
type = "object"
26+
required = [ "action", "msg",]
27+
28+
[properties.action]
29+
enum = [ "start", "interrupt", "shutdown", "restart",]
30+
description = "Action performed by the Kernel Manager.\n\nThis is a required field.\n\nPossible values:\n\n1. start\n A kernel has been started with the given kernel id.\n\n2. interrupt\n A kernel has been interrupted for the given kernel id.\n\n3. shutdown\n A kernel has been shut down for the given kernel id.\n\n4. restart\n A kernel has been restarted for the given kernel id.\n"
31+
32+
[properties.kernel_id]
33+
type = "string"
34+
description = "Kernel id.\n\nThis is a required field for all actions and statuses except action start with status error.\n"
35+
36+
[properties.kernel_name]
37+
type = "string"
38+
description = "Name of the kernel.\n"
39+
40+
[properties.status]
41+
enum = [ "error", "success",]
42+
description = "Status received from a rest api operation to kernel server.\n\nThis is a required field.\n\nPossible values:\n\n1. error\n Error response from a rest api operation to kernel server.\n\n2. success\n Success response from a rest api operation to kernel server.\n"
43+
44+
[properties.status_code]
45+
type = "number"
46+
description = "Http response codes from a rest api operation to kernel server.\nExamples: 200, 400, 502, 503, 599 etc\n"
47+
48+
[properties.msg]
49+
type = "string"
50+
description = "Description of the event specified in action.\n"
51+
52+
[if.not.properties.status]
53+
const = "error"
54+
55+
[if.not.properties.action]
56+
const = "start"
57+
58+
[then]
59+
required = [ "kernel_id",]
60+
61+
.. tab-item:: YAML
62+
63+
.. code-block:: yaml
64+
65+
$schema: https://json-schema.org/draft/2020-12/schema
66+
$id: https://schema.jupyter.org/server/events/kernel-actions/v1/kernel-actions.schema.json
67+
version: 1
68+
title: Kernel Manager activities
69+
personal-data: true
70+
description: 'Record events of a kernel manager.
71+
72+
'
73+
type: object
74+
required:
75+
- action
76+
- msg
77+
properties:
78+
action:
79+
enum:
80+
- start
81+
- interrupt
82+
- shutdown
83+
- restart
84+
description: "Action performed by the Kernel Manager.\n\nThis is a required field.\n\nPossible values:\n\
85+
\n1. start\n A kernel has been started with the given kernel id.\n\n2. interrupt\n A kernel\
86+
\ has been interrupted for the given kernel id.\n\n3. shutdown\n A kernel has been shut down for\
87+
\ the given kernel id.\n\n4. restart\n A kernel has been restarted for the given kernel id.\n"
88+
kernel_id:
89+
type: string
90+
description: 'Kernel id.
91+
92+
93+
This is a required field for all actions and statuses except action start with status error.
94+
95+
'
96+
kernel_name:
97+
type: string
98+
description: 'Name of the kernel.
99+
100+
'
101+
status:
102+
enum:
103+
- error
104+
- success
105+
description: "Status received from a rest api operation to kernel server.\n\nThis is a required field.\n\
106+
\nPossible values:\n\n1. error\n Error response from a rest api operation to kernel server.\n\n\
107+
2. success\n Success response from a rest api operation to kernel server.\n"
108+
status_code:
109+
type: number
110+
description: 'Http response codes from a rest api operation to kernel server.
111+
112+
Examples: 200, 400, 502, 503, 599 etc
113+
114+
'
115+
msg:
116+
type: string
117+
description: 'Description of the event specified in action.
118+
119+
'
120+
if:
121+
not:
122+
properties:
123+
status:
124+
const: error
125+
action:
126+
const: start
127+
then:
128+
required:
129+
- kernel_id

‎docs/index.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. jupyter-schemas documentation master file, created by
2+
sphinx-quickstart on Fri Feb 23 14:44:15 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to jupyter-schemas's documentation!
7+
===========================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Contents:
12+
13+
example
14+
15+
16+
Indices and tables
17+
==================
18+
19+
* :ref:`genindex`
20+
* :ref:`modindex`
21+
* :ref:`search`

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎pyproject.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,12 @@ Source = "https://github.com/unknown/jupyter-schemas"
3636
test = [
3737
"pytest",
3838
]
39+
docs = [
40+
"pydata_sphinx_theme",
41+
"sphinx",
42+
"sphinx_design",
43+
"sphinx-jsonschema",
44+
]
3945

4046
[tool.hatch.version]
4147
path = "jupyter_schemas.py"

0 commit comments

Comments
 (0)