Add Sphinx doc and helper scripts

Signed-off-by: Travis F. Collins <[email protected]>
analogdevicesinc · Sep 9, 2024 · 8f716c1 · 8f716c1
1 parent 2667d3d
commit 8f716c1
Show file tree

Hide file tree

Showing 55 changed files with 3,398 additions and 0 deletions.
diff --git a/doc/doxygen/doxyfile.in b/doc/doxygen/doxyfile.in
@@ -0,0 +1,21 @@
+GENERATE_XML = YES
+INPUT = ../../include/iio
+OUTPUT_DIRECTORY = generated
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = "__api= " \
+                         "__check_ret= " \
+                         "__pure= " \
+                         "__cnst= "
+
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+
+EXCLUDE                = ../../iio-private.h \
+                         ../../debug.h \
+                         ../../iio-lock.h \
+                         ../../iiod-client.h \
+                         ../../sort.h \
+                         ../../network.h
diff --git a/doc/make.bat b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%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
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/doc/man_to_rst.py b/doc/man_to_rst.py
@@ -0,0 +1,58 @@
+# Convert man pages to reStructuredText
+import os
+
+manfolder = os.path.join(os.path.dirname(__file__), "..","build", "share","man")
+page = ['iio_attr','iio_info','iio_genxml','iio_rwdev','iio_reg','iio_stresstest']
+
+tools = {}
+
+for po in page:
+    print(f"Converting {po} to reStructuredText")
+    p = po + ".1"
+    fullpath = os.path.join(manfolder, p)
+    target = os.path.join("source", "tools", po + ".rst")
+    os.system(f"pandoc --from man --to rst {fullpath} -o {target}")
+
+    # Add title to rst file
+    with open(target, 'r') as file:
+        data = file.readlines()
+
+    # Downgrade all headers by one level
+    for i in range(len(data)):
+        if data[i].startswith("="):
+            data[i] = data[i].replace("=", "-")
+        if data[i].startswith("#"):
+            data[i] = data[i].replace("#", "=")
+
+    data.insert(0, f"{po}\n")
+    data.insert(1, "=" * len(po) + "\n")
+
+    # Remove NAME line and the following line
+    for i in range(len(data)):
+        if data[i].startswith("NAME"):
+            data.pop(i)
+            data.pop(i)
+            ref = data[i+1]
+            print(f"Reference: {ref}")
+            tool = ref.split("-")[0].strip()
+            description = ref.split("-")[1].strip()
+            tools[tool] = description
+            break
+
+    with open(target, 'w') as file:
+        file.writelines(data)
+
+# Build index for cli tools
+print("Building index for cli tools")
+
+index = os.path.join("source", "tools", "index.rst")
+
+with open(index, 'w') as file:
+    file.write("Command Line Tools\n")
+    file.write("==================\n\n")
+    file.write(".. toctree::\n")
+    file.write("   :maxdepth: 1\n\n")
+    for tool in tools:
+        file.write(f"   {tool}\n")
+    file.write("\n\n")
+
diff --git a/doc/requirements_doc.txt b/doc/requirements_doc.txt
@@ -0,0 +1,7 @@
+sphinx
+https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz
+sphinxcontrib.wavedrom
+myst-parser
+breathe
+sphinx-inline-tabs
+sphinxcontrib-matlabdomain
diff --git a/doc/source/_static/codemodel.svg b/doc/source/_static/codemodel.svg
diff --git a/doc/source/_static/libiio_commands.png b/doc/source/_static/libiio_commands.png
diff --git a/doc/source/_static/libiio_details_readbuf.png b/doc/source/_static/libiio_details_readbuf.png
diff --git a/doc/source/_static/libiio_farview.png b/doc/source/_static/libiio_farview.png
diff --git a/doc/source/_static/libiio_highspeed_interface.png b/doc/source/_static/libiio_highspeed_interface.png
diff --git a/doc/source/_static/libiio_lowspeed_interface.png b/doc/source/_static/libiio_lowspeed_interface.png
diff --git a/doc/source/_static/libiio_open_command.png b/doc/source/_static/libiio_open_command.png
diff --git a/doc/source/_static/libiio_readbuf_command.png b/doc/source/_static/libiio_readbuf_command.png
diff --git a/doc/source/_static/libiio_route_highspeed.png b/doc/source/_static/libiio_route_highspeed.png
diff --git a/doc/source/_static/libiio_route_lowspeed.png b/doc/source/_static/libiio_route_lowspeed.png
diff --git a/doc/source/_static/libiio_route_zerocopy.png b/doc/source/_static/libiio_route_zerocopy.png
diff --git a/doc/source/api.rst b/doc/source/api.rst
@@ -0,0 +1,21 @@
+Library API
+-----------
+
+libiio at its base is a C library. The API is designed to be as simple as possible, while still providing access to all the features of the IIO subsystem. Support for other languages is provided through bindings to the C API.
+
+This section provides a detailed description of the C API. The API is divided into several categories, each of which is described in a separate page.
+
+.. toctree::
+    :maxdepth: 2
+
+    api/c/top
+    api/c/scan
+    api/c/attributes
+    api/c/context
+    api/c/device
+    api/c/channel
+    api/c/buffer
+    api/c/event
+    api/c/hwmon
+    api/c/debug
+
diff --git a/doc/source/api/c/attributes.rst b/doc/source/api/c/attributes.rst
@@ -0,0 +1,6 @@
+Attribute Functions
+===================
+
+.. doxygengroup:: Attributes
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/buffer.rst b/doc/source/api/c/buffer.rst
@@ -0,0 +1,14 @@
+Buffer Functions
+==================
+
+.. doxygengroup:: Buffer
+    :content-only:
+    :members:
+
+.. doxygengroup:: Block
+    :content-only:
+    :members:
+
+.. doxygengroup:: Stream
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/channel.rst b/doc/source/api/c/channel.rst
@@ -0,0 +1,6 @@
+Channel Functions
+==================
+
+.. doxygengroup:: Channel
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/context.rst b/doc/source/api/c/context.rst
@@ -0,0 +1,6 @@
+Context Functions
+==================
+
+.. doxygengroup:: Context
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/debug.rst b/doc/source/api/c/debug.rst
@@ -0,0 +1,6 @@
+Debug and Low-Level Functions
+=============================
+
+.. doxygengroup:: Debug
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/device.rst b/doc/source/api/c/device.rst
@@ -0,0 +1,6 @@
+Device Functions
+==================
+
+.. doxygengroup:: Device
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/event.rst b/doc/source/api/c/event.rst
@@ -0,0 +1,6 @@
+Event Handling Functions
+========================
+
+.. doxygengroup:: Events
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/hwmon.rst b/doc/source/api/c/hwmon.rst
@@ -0,0 +1,6 @@
+Hardware Monitoring Devices
+=======================================================
+
+.. doxygengroup:: Hwmon
+    :content-only:
+    :members:
diff --git a/doc/source/api/c/scan.rst b/doc/source/api/c/scan.rst
@@ -0,0 +1,20 @@
+Scanning Functions
+==================
+
+.. doxygenfunction:: iio_scan
+
+
+.. doxygenfunction:: iio_scan_destroy
+
+
+.. doxygenfunction:: iio_scan_get_results_count
+
+
+.. doxygenfunction:: iio_scan_get_description
+
+
+.. doxygenfunction:: iio_scan_get_uri
+
+
+.. .. doxygenstruct:: iio_scan
+
diff --git a/doc/source/api/c/top.rst b/doc/source/api/c/top.rst
@@ -0,0 +1,6 @@
+Top-Level Functions
+===================
+
+.. doxygengroup:: TopLevel
+    :content-only:
+    :members:
diff --git a/doc/source/api/python/buffer.rst b/doc/source/api/python/buffer.rst
@@ -0,0 +1,7 @@
+Buffer
+==================
+
+Members
+--------------
+.. autoclass:: iio.Buffer
+   :members:
diff --git a/doc/source/api/python/channel.rst b/doc/source/api/python/channel.rst
@@ -0,0 +1,18 @@
+Channels
+==================
+
+Members
+--------------
+.. autoclass:: iio.Channel
+   :members:
+
+--------------------
+
+Channel attributes
+--------------------
+.. autoclass:: iio.DataFormat
+   :members:
+.. autoclass:: iio.ChannelModifier
+   :members:
+.. autoclass:: iio.ChannelType
+   :members:
diff --git a/doc/source/api/python/context.rst b/doc/source/api/python/context.rst
@@ -0,0 +1,20 @@
+Contexts
+==================
+
+Members
+--------------
+.. autoclass:: iio.Context
+   :members:
+
+.. autoclass:: iio.LocalContext
+   :members:
+   :inherited-members:
+
+.. autoclass:: iio.XMLContext
+   :members:
+   :inherited-members:
+
+.. autoclass:: iio.NetworkContext
+   :members:
+   :inherited-members:
+
diff --git a/doc/source/api/python/device.rst b/doc/source/api/python/device.rst
@@ -0,0 +1,20 @@
+Device
+==================
+
+Members
+--------------
+.. autoclass:: iio.Device
+   :members:
+   :inherited-members:
+
+------------------
+
+.. Device attributes
+.. ------------------
+.. .. autoclass:: iio.DeviceDebugAttr
+..    :members:
+..    :inherited-members:
+.. .. autoclass:: iio.DeviceBufferAttr
+..    :members:
+..    :inherited-members:
+
diff --git a/doc/source/api/python/examples.rst b/doc/source/api/python/examples.rst
@@ -0,0 +1,31 @@
+Examples
+==================
+
+
+Complete Application Examples
+------------------------------
+.. toctree::
+   iio_readdev
+   iio_writedev
+   iio_attr
+   iio_info
+
+
+Code Snippets
+-----------------------------
+
+Scan contexts and list channels of each device
+
+.. code-block:: python
+
+ import iio
+
+ for ctxname in iio.scan_contexts():
+     ctx = iio.Context(ctxname)
+     for dev in ctx.devices:
+         if dev.channels:
+             for chan in dev.channels:
+                 print("{} - {} - {}".format(ctxname, dev.name, chan._id))
+         else:
+             print("{} - {}".format(ctxname, dev.name))
+
diff --git a/doc/source/api/python/iio_attr.rst b/doc/source/api/python/iio_attr.rst
@@ -0,0 +1,9 @@
+iio_attr
+======================
+| iio_attr is part of the libiio package, a library that has been developed to ease the development of software interfacing Linux Industrial I/O (IIO) devices.
+| This tool is written using the libiio Python bindings. It works in a very similar way of how the base iio_attr works. You can find more information about it on this `page <https://wiki.analog.com/resources/tools-software/linux-software/libiio/iio_attr>`_.
+
+
+.. literalinclude:: ../../../../bindings/python/examples/iio_attr.py
+   :language: python
+
diff --git a/doc/source/api/python/iio_info.rst b/doc/source/api/python/iio_info.rst
@@ -0,0 +1,10 @@
+iio_info
+=====================
+| iio_info is part of the libiio package, a library that has been developed to ease the development of software interfacing Linux Industrial I/O (IIO) devices.
+| This tool is written using the libiio Python bindings. It works in the same way as the base iio_info works. You can find more information about it on this `page <https://wiki.analog.com/resources/tools-software/linux-software/libiio/iio_info>`_.
+
+
+
+.. literalinclude:: ../../../../bindings/python/examples/iio_info.py
+   :language: python
+
diff --git a/doc/source/api/python/iio_readdev.rst b/doc/source/api/python/iio_readdev.rst
@@ -0,0 +1,9 @@
+iio_readdev
+=====================
+| iio_readdev is part of the libiio package, a library that has been developed to ease the development of software interfacing Linux Industrial I/O (IIO) devices.
+| This tool is written using the libiio Python bindings. It works in the same way as the base iio_readdev works. You can find more information about it on this `page <https://wiki.analog.com/resources/tools-software/linux-software/libiio/iio_readdev?s[]=readdev>`_.
+
+
+.. literalinclude:: ../../../../bindings/python/examples/iio_readdev.py
+   :language: python
+
diff --git a/doc/source/api/python/iio_writedev.rst b/doc/source/api/python/iio_writedev.rst
@@ -0,0 +1,9 @@
+iio_writedev
+=====================
+| iio_writedev is part of the libiio package, a library that has been developed to ease the development of software interfacing Linux Industrial I/O (IIO) devices.
+| This tool is written using the libiio Python bindings. It works in the same way as the base iio_writedev works. You can find more information about it on this `page <https://wiki.analog.com/resources/tools-software/linux-software/libiio/iio_writedev>`_.
+
+
+.. literalinclude:: ../../../../bindings/python/examples/iio_writedev.py
+   :language: python
+