Skip to content

Commit a48c87f

Browse files
dwsusedwsuse
committed
doc: Build ReST documantion as standalone target
In order to feed readthedocs with documecation we have to build the ReST documentation and store it the source tree. To avoid cluttering the root dir of the documantion directory move the generation of the *.rst docs into the rst subdir. Unfortunatly, meson doesn't have an option to generate the newly files into subdir. So move the rst build instruction into rst/meson.build. While at it, split the whole documentation into sections. We want to replace any VERSION string in the documantion. Instead just addressing conf.py we process all files in one go for consistency reasons. Signed-off-by: Daniel Wagner <[email protected]>
1 parent 033449f commit a48c87f

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)