Add Sphinx doc and helper scripts

Signed-off-by: Travis F. Collins <[email protected]>

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

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

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

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")
+

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

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
+

doc/source/api/c/attributes.rst

@@ -0,0 +1,6 @@
+Attribute Functions
+===================
+
+.. doxygengroup:: Attributes
+    :content-only:
+    :members:

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:

doc/source/api/c/channel.rst

@@ -0,0 +1,6 @@
+Channel Functions
+==================
+
+.. doxygengroup:: Channel
+    :content-only:
+    :members:

doc/source/api/c/context.rst

@@ -0,0 +1,6 @@
+Context Functions
+==================
+
+.. doxygengroup:: Context
+    :content-only:
+    :members:

doc/source/api/c/debug.rst

@@ -0,0 +1,6 @@
+Debug and Low-Level Functions
+=============================
+
+.. doxygengroup:: Debug
+    :content-only:
+    :members:

doc/source/api/c/device.rst

@@ -0,0 +1,6 @@
+Device Functions
+==================
+
+.. doxygengroup:: Device
+    :content-only:
+    :members:

doc/source/api/c/event.rst

@@ -0,0 +1,6 @@
+Event Handling Functions
+========================
+
+.. doxygengroup:: Events
+    :content-only:
+    :members:

doc/source/api/c/hwmon.rst

@@ -0,0 +1,6 @@
+Hardware Monitoring Devices
+=======================================================
+
+.. doxygengroup:: Hwmon
+    :content-only:
+    :members:

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
+

doc/source/api/c/top.rst

@@ -0,0 +1,6 @@
+Top-Level Functions
+===================
+
+.. doxygengroup:: TopLevel
+    :content-only:
+    :members:

doc/source/api/python/buffer.rst

@@ -0,0 +1,7 @@
+Buffer
+==================
+
+Members
+--------------
+.. autoclass:: iio.Buffer
+   :members:

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:

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:
+

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:
+

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))
+

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
+

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
+

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
+