diff options
Diffstat (limited to 'doc/readthedocs')
26 files changed, 358 insertions, 0 deletions
diff --git a/doc/readthedocs/Makefile b/doc/readthedocs/Makefile new file mode 100644 index 0000000..76911e9 --- /dev/null +++ b/doc/readthedocs/Makefile @@ -0,0 +1,22 @@ +# Minimal makefile for Sphinx documentation +# +.DEFAULT_GOAL := help + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +.PHONY: help +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +.PHONY: Makefile +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/readthedocs/conf.py b/doc/readthedocs/conf.py new file mode 100644 index 0000000..a5b3960 --- /dev/null +++ b/doc/readthedocs/conf.py @@ -0,0 +1,34 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + + +# -- Project information ----------------------------------------------------- + +project = 'nvme-stas' +copyright = 'Copyright (c) 2022, Dell Inc. or its subsidiaries. All rights reserved.' +author = 'Martin Belanger <martin.belanger@dell.com>' +master_doc = 'index' + +version = '@VERSION@' +release = '@VERSION@' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autosummary', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['Thumbs.db', '.DS_Store'] diff --git a/doc/readthedocs/environment.txt b/doc/readthedocs/environment.txt new file mode 100644 index 0000000..5388c88 --- /dev/null +++ b/doc/readthedocs/environment.txt @@ -0,0 +1 @@ +sphinx==5.3.0 diff --git a/doc/readthedocs/index.rst b/doc/readthedocs/index.rst new file mode 100644 index 0000000..ad927fe --- /dev/null +++ b/doc/readthedocs/index.rst @@ -0,0 +1,30 @@ +Welcome to nvme-stas's documentation! +===================================== + +What does nvme-stas provide? + +* A Central Discovery Controller (CDC) client for Linux +* Asynchronous Event Notifications (AEN) handling +* Automated NVMe subsystem connection controls +* Error handling and reporting +* Automatic (zeroconf) and Manual configuration + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + installation.rst + nvme-stas.rst + stafd-index.rst + stacd-index.rst + stasadm.rst + sys.conf.rst + stas-config.target.rst + stas-config@.service.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/readthedocs/installation.rst b/doc/readthedocs/installation.rst new file mode 100644 index 0000000..95750e2 --- /dev/null +++ b/doc/readthedocs/installation.rst @@ -0,0 +1,28 @@ +Installation +============ + +Debian / Ubuntu: +---------------- + +.. code-block:: sh + + $ apt-get install nvme-stas + +Fedora / Red Hat: +----------------- + +.. code-block:: sh + + $ dnf install nvme-stas + +Python Version +-------------- + +The latest Python 3 version is always recommended, since it has all the latest bells and +whistles. libnvme supports Python 3.6 and above. + +Dependencies +------------ + +nvme-stas is built on top of libnvme, which is used to interact with the kernel's NVMe driver (i.e. drivers/nvme/host/). To support all the features of nvme-stas, several changes to the Linux kernel are required. nvme-stas can also operate with older kernels, but with limited functionality. Kernel 5.18 provides all the features needed by nvme-stas. nvme-stas can also work with older kernels that include back-ported changes to the NVMe driver. + diff --git a/doc/readthedocs/make.bat b/doc/readthedocs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/doc/readthedocs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/doc/readthedocs/meson.build b/doc/readthedocs/meson.build new file mode 100644 index 0000000..a8e2305 --- /dev/null +++ b/doc/readthedocs/meson.build @@ -0,0 +1,64 @@ +# Copyright (c) 2022, Dell Inc. or its subsidiaries. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# See the LICENSE file for details. +# +# This file is part of NVMe STorage Appliance Services (nvme-stas). +# +# Authors: Martin Belanger <Martin.Belanger@dell.com> +# + +pandoc = find_program('pandoc', required: true) + +components = [ + 'conf.py', + 'Makefile', + 'make.bat', + 'index.rst', + 'environment.txt', + 'installation.rst', + 'nvme-stas.rst', + 'org.nvmexpress.stac.debug.rst', + 'org.nvmexpress.stac.rst', + 'org.nvmexpress.staf.debug.rst', + 'org.nvmexpress.staf.rst', + 'stacctl.rst', + 'stacd-index.rst', + 'stacd.conf.rst', + 'stacd.rst', + 'stacd.service.rst', + 'stafctl.rst', + 'stafd-index.rst', + 'stafd.conf.rst', + 'stafd.rst', + 'stafd.service.rst', + 'stas-config.target.rst', + 'stas-config@.service.rst', + 'stasadm.rst', + 'sys.conf.rst', +] +foreach component : components + configure_file( + input: component, + output: component, + configuration: conf, + ) +endforeach + +foreach tuple: html_files + stem = tuple[0] + html_file = tuple[1] + rst = '_' + stem + '.rst' + custom_target( + rst, + input: html_file, + output: rst, + build_by_default: true, + command: [ + pandoc, + '-f', 'html', + '-t', 'rst', + '-o', '@OUTPUT@', + '@INPUT@' + ] + ) +endforeach diff --git a/doc/readthedocs/nvme-stas.rst b/doc/readthedocs/nvme-stas.rst new file mode 100644 index 0000000..e7383f9 --- /dev/null +++ b/doc/readthedocs/nvme-stas.rst @@ -0,0 +1,5 @@ +========================== +STorage Appliance Services +========================== + +.. include:: _nvme-stas.rst diff --git a/doc/readthedocs/org.nvmexpress.stac.debug.rst b/doc/readthedocs/org.nvmexpress.stac.debug.rst new file mode 100644 index 0000000..e82f2d7 --- /dev/null +++ b/doc/readthedocs/org.nvmexpress.stac.debug.rst @@ -0,0 +1,7 @@ +========================= +org.nvmexpress.stac.debug +========================= +.. module:: org.nvmexpress.stac.debug + +.. include:: _org.nvmexpress.stac.debug.rst + diff --git a/doc/readthedocs/org.nvmexpress.stac.rst b/doc/readthedocs/org.nvmexpress.stac.rst new file mode 100644 index 0000000..5132fad --- /dev/null +++ b/doc/readthedocs/org.nvmexpress.stac.rst @@ -0,0 +1,7 @@ +=================== +org.nvmexpress.stac +=================== +.. module:: org.nvmexpress.stac + +.. include:: _org.nvmexpress.stac.rst + diff --git a/doc/readthedocs/org.nvmexpress.staf.debug.rst b/doc/readthedocs/org.nvmexpress.staf.debug.rst new file mode 100644 index 0000000..8161db5 --- /dev/null +++ b/doc/readthedocs/org.nvmexpress.staf.debug.rst @@ -0,0 +1,7 @@ +========================= +org.nvmexpress.staf.debug +========================= +.. module:: org.nvmexpress.staf.debug + +.. include:: _org.nvmexpress.staf.debug.rst + diff --git a/doc/readthedocs/org.nvmexpress.staf.rst b/doc/readthedocs/org.nvmexpress.staf.rst new file mode 100644 index 0000000..26ef29d --- /dev/null +++ b/doc/readthedocs/org.nvmexpress.staf.rst @@ -0,0 +1,7 @@ +=================== +org.nvmexpress.staf +=================== +.. module:: org.nvmexpress.staf + +.. include:: _org.nvmexpress.staf.rst + diff --git a/doc/readthedocs/stacctl.rst b/doc/readthedocs/stacctl.rst new file mode 100644 index 0000000..60fe075 --- /dev/null +++ b/doc/readthedocs/stacctl.rst @@ -0,0 +1,7 @@ +======= +stacctl +======= +.. module:: stacctl + +.. include:: _stacctl.rst + diff --git a/doc/readthedocs/stacd-index.rst b/doc/readthedocs/stacd-index.rst new file mode 100644 index 0000000..cebd5f4 --- /dev/null +++ b/doc/readthedocs/stacd-index.rst @@ -0,0 +1,13 @@ +STorage Appliance Connector +=========================== + +.. toctree:: + :maxdepth: 1 + + stacd.rst + stacd.conf.rst + stacd.service.rst + stacctl.rst + org.nvmexpress.stac.rst + org.nvmexpress.stac.debug.rst + diff --git a/doc/readthedocs/stacd.conf.rst b/doc/readthedocs/stacd.conf.rst new file mode 100644 index 0000000..2a0cad9 --- /dev/null +++ b/doc/readthedocs/stacd.conf.rst @@ -0,0 +1,7 @@ +========== +stacd.conf +========== +.. module:: stacd.conf + +.. include:: _stacd.conf.rst + diff --git a/doc/readthedocs/stacd.rst b/doc/readthedocs/stacd.rst new file mode 100644 index 0000000..2cf809b --- /dev/null +++ b/doc/readthedocs/stacd.rst @@ -0,0 +1,8 @@ +===== +stacd +===== +.. module:: stacd + +.. include:: _stacd.rst + + diff --git a/doc/readthedocs/stacd.service.rst b/doc/readthedocs/stacd.service.rst new file mode 100644 index 0000000..7294710 --- /dev/null +++ b/doc/readthedocs/stacd.service.rst @@ -0,0 +1,7 @@ +============= +stacd.service +============= +.. module:: stacd.service + +.. include:: _stacd.service.rst + diff --git a/doc/readthedocs/stafctl.rst b/doc/readthedocs/stafctl.rst new file mode 100644 index 0000000..849e37c --- /dev/null +++ b/doc/readthedocs/stafctl.rst @@ -0,0 +1,7 @@ +======= +stafctl +======= +.. module:: stafctl + +.. include:: _stafctl.rst + diff --git a/doc/readthedocs/stafd-index.rst b/doc/readthedocs/stafd-index.rst new file mode 100644 index 0000000..f4d1292 --- /dev/null +++ b/doc/readthedocs/stafd-index.rst @@ -0,0 +1,13 @@ +STorage Appliance Finder +======================== + +.. toctree:: + :maxdepth: 1 + + stafd.rst + stafd.conf.rst + stafd.service.rst + stafctl.rst + org.nvmexpress.staf.rst + org.nvmexpress.staf.debug.rst + diff --git a/doc/readthedocs/stafd.conf.rst b/doc/readthedocs/stafd.conf.rst new file mode 100644 index 0000000..a03d93a --- /dev/null +++ b/doc/readthedocs/stafd.conf.rst @@ -0,0 +1,7 @@ +========== +stafd.conf +========== +.. module:: stafd.conf + +.. include:: _stafd.conf.rst + diff --git a/doc/readthedocs/stafd.rst b/doc/readthedocs/stafd.rst new file mode 100644 index 0000000..a12298c --- /dev/null +++ b/doc/readthedocs/stafd.rst @@ -0,0 +1,7 @@ +===== +stafd +===== +.. module:: stafd + +.. include:: _stafd.rst + diff --git a/doc/readthedocs/stafd.service.rst b/doc/readthedocs/stafd.service.rst new file mode 100644 index 0000000..771189c --- /dev/null +++ b/doc/readthedocs/stafd.service.rst @@ -0,0 +1,7 @@ +============= +stafd.service +============= +.. module:: stafd.service + +.. include:: _stafd.service.rst + diff --git a/doc/readthedocs/stas-config.target.rst b/doc/readthedocs/stas-config.target.rst new file mode 100644 index 0000000..cf88fa9 --- /dev/null +++ b/doc/readthedocs/stas-config.target.rst @@ -0,0 +1,7 @@ +================== +stas-config.target +================== +.. module:: stas-config.target + +.. include:: _stas-config.target.rst + diff --git a/doc/readthedocs/stas-config@.service.rst b/doc/readthedocs/stas-config@.service.rst new file mode 100644 index 0000000..7af78ed --- /dev/null +++ b/doc/readthedocs/stas-config@.service.rst @@ -0,0 +1,7 @@ +==================== +stas-config@.service +==================== +.. module:: stas-config@.service + +.. include:: _stas-config@.service.rst + diff --git a/doc/readthedocs/stasadm.rst b/doc/readthedocs/stasadm.rst new file mode 100644 index 0000000..54489a8 --- /dev/null +++ b/doc/readthedocs/stasadm.rst @@ -0,0 +1,7 @@ +======= +stasadm +======= +.. module:: stasadm + +.. include:: _stasadm.rst + diff --git a/doc/readthedocs/sys.conf.rst b/doc/readthedocs/sys.conf.rst new file mode 100644 index 0000000..05ab0f0 --- /dev/null +++ b/doc/readthedocs/sys.conf.rst @@ -0,0 +1,7 @@ +======== +sys.conf +======== +.. module:: sys.conf + +.. include:: _sys.conf.rst + |