Skip to content

Commit c26d71f

Browse files
dwsusedwsuse
authored
Merge pull request #343 from igaw/build-rst-doc
doc: Build ReST documantion as standalone target
2 parents 0f85f87 + a48c87f commit c26d71f

17 files changed

Lines changed: 20629 additions & 82 deletions

‎doc/conf.py‎

Lines changed: 3 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,15 @@
44
# list see the documentation:
55
# https://www.sphinx-doc.org/en/master/usage/configuration.html
66

7-
# -- Path setup --------------------------------------------------------------
8-
9-
# If extensions (or modules to document with autodoc) are in another directory,
10-
# add these directories to sys.path here. If the directory is relative to the
11-
# documentation root, use os.path.abspath to make it absolute, like shown here.
12-
#
13-
# import os
14-
# import sys
15-
# sys.path.insert(0, os.path.abspath('.'))
16-
177

188
# -- Project information -----------------------------------------------------
199

2010
project = 'libnvme'
2111
copyright = '2020, Keith Busch'
2212
author = 'Keith Busch <[email protected]>'
23-
master_doc = 'libnvme'
13+
master_doc = 'index'
2414

25-
# The full version, including alpha/beta/rc tags
26-
release = '0.1'
15+
release = '1.0'
2716

2817

2918
# -- General configuration ---------------------------------------------------
@@ -40,34 +29,4 @@
4029
# List of patterns, relative to source directory, that match files and
4130
# directories to ignore when looking for source files.
4231
# This pattern also affects html_static_path and html_extra_path.
43-
exclude_patterns = ['html', 'man', 'index.rst', 'Thumbs.db', '.DS_Store']
44-
45-
46-
# -- Options for HTML output -------------------------------------------------
47-
48-
# The theme to use for HTML and HTML Help pages. See the documentation for
49-
# a list of builtin themes.
50-
#
51-
#html_theme = 'alabaster'
52-
53-
# Add any paths that contain custom static files (such as style sheets) here,
54-
# relative to this directory. They are copied after the builtin static files,
55-
# so a file named "default.css" will overwrite the builtin "default.css".
56-
html_static_path = ['sphinx-static']
57-
html_context = {
58-
'css_files': [
59-
'_static/theme_overrides.css',
60-
],
61-
}
62-
63-
html_use_smartypants = False
64-
pygments_style = 'sphinx'
65-
66-
htmlhelp_basename = 'libnvme'
67-
68-
try:
69-
import sphinx_rtd_theme
70-
html_theme = 'sphinx_rtd_theme'
71-
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
72-
except ImportError:
73-
sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
32+
exclude_patterns = ['html', 'man', 'Thumbs.db', '.DS_Store']

‎doc/conf.py.in‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
8+
# -- Project information -----------------------------------------------------
9+
10+
project = 'libnvme'
11+
copyright = '2020, Keith Busch'
12+
author = 'Keith Busch <[email protected]>'
13+
master_doc = 'index'
14+
15+
release = '@VERSION@'
16+
17+
18+
# -- General configuration ---------------------------------------------------
19+
20+
# Add any Sphinx extension module names here, as strings. They can be
21+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
22+
# ones.
23+
extensions = [
24+
]
25+
26+
# Add any paths that contain templates here, relative to this directory.
27+
templates_path = ['_templates']
28+
29+
# List of patterns, relative to source directory, that match files and
30+
# directories to ignore when looking for source files.
31+
# This pattern also affects html_static_path and html_extra_path.
32+
exclude_patterns = ['html', 'man', 'Thumbs.db', '.DS_Store']

‎doc/config-schema.json.in‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://github.com/linux-nvme/libnvme/doc/config-schema.json",
4+
"title": "config.json",
5+
"description": "libnvme JSON configuration",
6+
"type": "object",
7+
"properties": {
8+
"hosts": {
9+
"description": "Array of NVMe Host properties",
10+
"type": "array",
11+
"items": { "$ref": "#/$defs/host" }
12+
}
13+
},
14+
"$defs": {
15+
"host": {
16+
"description": "NVMe Host properties",
17+
"type": "object",
18+
"properties": {
19+
"hostnqn": {
20+
"description": "NVMe host NQN",
21+
"type": "string",
22+
"maxLength": 223
23+
},
24+
"hostid": {
25+
"description": "NVMe host ID",
26+
"type": "string"
27+
},
28+
"hostsymname": {
29+
"description": "NVMe host symbolic name",
30+
"type": "string"
31+
},
32+
"required": [ "hostnqn" ],
33+
"subsystems": {
34+
"description": "Array of NVMe subsystem properties",
35+
"type": "array",
36+
"items": { "$ref": "#/$defs/subsystem" }
37+
}
38+
}
39+
},
40+
"subsystem": {
41+
"description": "NVMe subsystem properties",
42+
"type": "object",
43+
"properties": {
44+
"nqn": {
45+
"description": "Subsystem NQN",
46+
"type": "string",
47+
"maxLength": 223
48+
},
49+
"ports": {
50+
"description": "Array of NVMe subsystem ports",
51+
"type": "array",
52+
"items": { "$ref": "#/$defs/port" }
53+
},
54+
"required": [ "nqn" ]
55+
}
56+
},
57+
"port": {
58+
"description": "NVMe subsystem port",
59+
"type": "object",
60+
"properties": {
61+
"transport": {
62+
"description": "Transport type",
63+
"type": "string"
64+
},
65+
"traddr": {
66+
"description": "Transport address",
67+
"type": "string"
68+
},
69+
"host_traddr": {
70+
"description": "Host transport address",
71+
"type": "string"
72+
},
73+
"host_iface": {
74+
"description": "Host interface name",
75+
"type": "string"
76+
},
77+
"trsvcid": {
78+
"description": "Transport service identifier",
79+
"type": "string"
80+
},
81+
"dhchap_key": {
82+
"description": "Host DH-HMAC-CHAP key",
83+
"type": "string"
84+
},
85+
"dhchap_ctrl_key": {
86+
"description": "Controller DH-HMAC-CHAP key",
87+
"type": "string"
88+
},
89+
"nr_io_queues": {
90+
"description": "Number of I/O queues",
91+
"type": "integer"
92+
},
93+
"nr_write_queues": {
94+
"description": "Number of write queues",
95+
"type": "integer"
96+
},
97+
"nr_poll_queues": {
98+
"description": "Number of poll queues",
99+
"type": "integer"
100+
},
101+
"queue_size": {
102+
"description": "Queue size",
103+
"type": "integer"
104+
},
105+
"keep_alive_tmo": {
106+
"description": "Keep-Alive timeout (in seconds)",
107+
"type": "integer"
108+
},
109+
"reconnect_delay": {
110+
"description": "Reconnect delay (in seconds)",
111+
"type": "integer"
112+
},
113+
"ctrl_loss_tmo": {
114+
"description": "Controller loss timeout (in seconds)",
115+
"type": "integer"
116+
},
117+
"fast_io_fail_tmo": {
118+
"description": "Fast I/O Fail timeout (in seconds)",
119+
"type": "integer",
120+
"default": 600
121+
},
122+
"tos": {
123+
"description": "Type of service",
124+
"type": "integer",
125+
"default": -1
126+
},
127+
"duplicate_connect": {
128+
"description": "Allow duplicate connections",
129+
"type": "boolean",
130+
"default": false
131+
},
132+
"disable_sqflow": {
133+
"description": "Explicitly disable SQ flow control",
134+
"type": "boolean",
135+
"default": false
136+
},
137+
"hdr_digest": {
138+
"description": "Enable header digest",
139+
"type": "boolean",
140+
"default": false
141+
},
142+
"data_digest": {
143+
"description": "Enable data digest",
144+
"type": "boolean",
145+
"default": false
146+
},
147+
"tls": {
148+
"description": "Enable TLS encryption",
149+
"type": "boolean",
150+
"default": false
151+
},
152+
"persistent": {
153+
"description": "Create persistent discovery connection",
154+
"type": "boolean"
155+
},
156+
"discovery": {
157+
"description": "Connect to a discovery controller",
158+
"type": "boolean"
159+
}
160+
},
161+
"required": [ "transport" ]
162+
}
163+
}
164+
}

‎doc/index.rst‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
1-
.. libnvme documentation master file, created by
2-
sphinx-quickstart on Thu Feb 6 17:59:42 2020.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
5-
61
Welcome to libnvme's documentation!
72
===================================
83

94
.. toctree::
105
:maxdepth: 2
116
:caption: Contents:
127

13-
libnvme
8+
.. include:: rst/types.rst
9+
.. include:: rst/ioctl.rst
10+
.. include:: rst/fabrics.rst
11+
.. include:: rst/linux.rst
12+
.. include:: rst/tree.rst
13+
.. include:: rst/filters.rst
14+
.. include:: rst/util.rst
15+
.. include:: rst/log.rst
1416

1517

1618
Indices and tables

‎doc/index.rst.in‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Welcome to libnvme's documentation!
2+
===================================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
:caption: Contents:
7+
8+
.. include:: rst/types.rst
9+
.. include:: rst/ioctl.rst
10+
.. include:: rst/fabrics.rst
11+
.. include:: rst/linux.rst
12+
.. include:: rst/tree.rst
13+
.. include:: rst/filters.rst
14+
.. include:: rst/util.rst
15+
.. include:: rst/log.rst
16+
17+
18+
Indices and tables
19+
==================
20+
21+
* :ref:`genindex`
22+
* :ref:`modindex`
23+
* :ref:`search`

‎doc/meson.build‎

Lines changed: 11 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ sphinx_sources = [
2525
'config-schema.json'
2626
]
2727

28+
static_sources = []
29+
foreach file : sphinx_sources
30+
static_sources += configure_file(input: file + '.in',
31+
output: file,
32+
configuration: substs)
33+
endforeach
34+
35+
subdir('rst')
36+
2837
want_docs = get_option('docs')
2938
want_docs_build = get_option('docs-build')
3039
if want_docs != 'false'
@@ -41,7 +50,7 @@ if want_docs != 'false'
4150
foreach file : files('../src/nvme/' + apif)
4251
subst = configure_file(
4352
input: file,
44-
output: '@BASENAME@.msubst',
53+
output: '@BASENAME@.subst',
4554
configuration: conf)
4655
c = run_command(list_man_pages, subst)
4756
man_pages = c.stdout().split()
@@ -73,37 +82,9 @@ if want_docs != 'false'
7382
htmldir = join_paths(get_option('htmldir'), 'nvme')
7483
sphinx_build = find_program('sphinx-build-3', 'sphinx-build')
7584
if sphinx_build.found() and want_docs_build
76-
cat = find_program('cat')
77-
rsts = []
78-
foreach apif : api_files
79-
afile = files('../src/nvme/' + apif)
80-
subst = configure_file(
81-
input: afile,
82-
output: '@[email protected]',
83-
configuration: conf)
84-
rst = custom_target(
85-
apif.underscorify() + '_rst',
86-
input: subst,
87-
output: '@BASENAME@._rst',
88-
capture: true,
89-
command: [kernel_doc,
90-
'-rst',
91-
'@INPUT@'])
92-
rsts += rst
93-
endforeach
94-
libnvme = custom_target(
95-
'libnvme',
96-
command: [ cat, '@INPUT@' ],
97-
capture: true,
98-
input: rsts,
99-
output: 'libnvme.rst')
100-
static_sources = []
101-
foreach file : sphinx_sources
102-
static_sources += configure_file(input: file, output: file, copy: true)
103-
endforeach
10485
custom_target(
10586
'generate_doc_html',
106-
input: [static_sources, libnvme],
87+
input: [static_sources, rst],
10788
output: 'html',
10889
command: [sphinx_build,
10990
'-b', 'html',

0 commit comments

Comments
 (0)