Bulk updates for doc pages

Signed-off-by: Travis F. Collins <travis.collins@analog.com>
analogdevicesinc · Aug 22, 2024 · 7cad2c5 · 7cad2c5
1 parent a899d82
commit 7cad2c5
Show file tree

Hide file tree

Showing 26 changed files with 268 additions and 82 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -21,6 +21,7 @@ jobs:
           cd build
           cmake .. -DWITH_MAN=ON -DHAVE_DNS_SD=OFF
           make
+          sudo make install
           cd ..
           cd docs
           pip install -r requirements_doc.txt

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -17,4 +17,5 @@ This section provides a detailed description of the C API. The API is divided in
     api/c/buffer
     api/c/event
     api/c/hwmon
-    api/c/debug
+    api/c/debug
+
diff --git a/docs/source/api/c/scan.rst b/docs/source/api/c/scan.rst
@@ -1,6 +1,20 @@
 Scanning Functions
 ==================
 
-.. doxygengroup:: Scan
-    :content-only:
-    :members:
+.. 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/docs/source/api/matlab/context.rst b/docs/source/api/matlab/context.rst
diff --git a/docs/source/api/matlab/index.md b/docs/source/api/matlab/index.md
diff --git a/docs/source/api/python/buffer.rst b/docs/source/api/python/buffer.rst
@@ -0,0 +1,7 @@
+Buffer
+==================
+
+Members
+--------------
+.. autoclass:: iio.Buffer
+   :members:
diff --git a/docs/source/api/python/channel.rst b/docs/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/docs/source/api/python/context.rst b/docs/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/docs/source/api/python/device.rst b/docs/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/docs/source/api/python/examples.rst b/docs/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/docs/source/api/python/iio_attr.rst b/docs/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/docs/source/api/python/iio_info.rst b/docs/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/docs/source/api/python/iio_readdev.rst b/docs/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/docs/source/api/python/iio_writedev.rst b/docs/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
+
diff --git a/docs/source/api/python/index.rst b/docs/source/api/python/index.rst
@@ -0,0 +1,47 @@
+Python Bindings
+===============
+
+Python bindings for the `Industrial I/O <../index.html>`_ interface library. 
+
+Installation
+############
+
+The libiio python bindings can be installed from pip
+
+.. code-block:: bash
+
+  (sudo) pip install pylibiio
+
+or by grabbing the source directly
+
+.. code-block:: bash
+
+  git clone https://github.com/analogdevicesinc/libiio.git
+  cd bindings/python
+  (sudo) python3 setup.py install
+
+.. note::
+
+  On Linux the libiio python bindings are sometimes installed in locations not on path. On Ubuntu this is a common fix
+
+  .. code-block:: bash
+
+    export PYTHONPATH=$PYTHONPATH:/usr/lib/python{python-version}/site-packages
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+Components
+##########
+
+.. toctree::
+   :maxdepth: 1
+
+   context
+   buffer
+   device
+   channel
+   trigger
+   examples
+
diff --git a/docs/source/api/python/trigger.rst b/docs/source/api/python/trigger.rst
@@ -0,0 +1,8 @@
+Trigger
+==================
+
+Members
+--------------
+.. autoclass:: iio.Trigger
+   :members:
+   :inherited-members:
diff --git a/docs/source/bindings.rst b/docs/source/bindings.rst
@@ -5,4 +5,4 @@ Bindings
 .. toctree::
     :maxdepth: 2
 
-    api/matlab/index
+    api/python/index
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,6 +10,13 @@
 os.system("doxygen doxyfile.in")
 os.chdir(cwd)
 
+# Add bindings and examples to path
+import sys
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "bindings", "python")))
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "bindings", "examples")))
+
+import iio
+
 # -- Project information -----------------------------------------------------
 project = 'libiio'
 year = datetime.datetime.now().year

diff --git a/docs/source/examples.md b/docs/source/examples.md
@@ -1,6 +1,6 @@
 # Examples
 
-This page provides a few examples of how to use the libIIO library. The examples are written in C and are intended to be used as a starting point for your own application. For other languages, please refer to the [Bindings](bindings.md) page.
+This page provides a few examples of how to use the libIIO library. The examples are written in C and are intended to be used as a starting point for your own application. For other languages, please refer to the [Bindings](bindings.rst) page.
 
 :::{note}
 To reduce verbosity, the error handling code has been omitted from the examples. In a real application, you should always check the return value of each function call.

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -11,13 +11,13 @@ It is portable: Using a single cross-platform API, it provides access to IIO dev
 
 It is entirely user-mode: No special privilege or elevation is required for the application to communicate with a device. One of the most powerful things about libiio is its [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call) style interface. Moving backends from USB to Networking to local embedded does not require any code changes. The users of the libIIO do not need to code any differently for the remote interaction, making it easy to move from remote (debug on PC over Ethernet) to local (deployed on embedded Linux).
 
-### What platforms are supported?
+## What platforms are supported?
 
 Any host running Linux, macOS, Windows, or OpenBSD/NetBSD, should be trivial to get libIIO running on. If you are interested in porting to other hosts that support either networking (socket interface), [libusb](https://libusb.info/) or serial, it should be very straightforward. [Pull Requests](https://github.com/analogdevicesinc/libiio/pulls) are always reviewed, and well written ones are normally accepted.
 
 The local backend and Linux daemon can run on any embedded Linux based system, from purpose built systems like [PlutoSDR](http://www.analog.com/plutosdr) or [ADALM2000](http://www.analog.com/adalm2000) to [Raspberry Pi](https://www.raspberrypi.org/) or [BeagleBoard](https://beagleboard.org/) to [Jetson](https://www.nvidia.com/en-us/autonomous-machines/jetson). [tiny-iiod](https://github.com/analogdevicesinc/libtinyiiod) requires a modern C compiler and is known to work on a variety of non-Linux frameworks including [Mbed](https://www.mbed.com/) and [FreeRTOS](https://www.freertos.org/).
 
-### Sounds good! How do I get started?
+## Sounds good! How do I get started?
 
 If you are using Linux, chances are your distribution already includes libIIO, so you probably just need to reference the `iio.h` header in your source.
 
@@ -27,11 +27,11 @@ If you prefer, you can also access the source directly from [github](https://git
 
 Once you have secured your access to the library and its header, please check the [libIIO API](https://analogdevicesinc.github.io/libiio/api/index.html) or the [libIIO examples](https://analogdevicesinc.github.io/libiio/examples/index.html).
 
-### Where is (insert my favourite language) support?
+## Where is (insert my favourite language) support?
 
 The mainline library is written in C, and has built in bindings for C++, Python and C# (C-Sharp). [Node.js](https://github.com/drom/node-iio) and [Rust](https://github.com/fpagliughi/rust-industrial-io) are maintained outside the main repo. If you are interested in creating more language bindings, please [reach out](https://github.com/analogdevicesinc/libiio/issues) to the developers by posting an issue on github.
 
-## Licensing
+# Licensing
 
 Libiio has been developed and is released under the terms of the GNU Lesser General Public License, version 2 or (at your option) any later version. This open-source license allows anyone to use the library for proprietary or open-source, commercial or non-commercial applications.
 

diff --git a/docs/source/install.md b/docs/source/install.md
@@ -39,9 +39,7 @@ Please reference your OS's package manager for the correct package names. Altern
 
 For macOS there are four options:
 
-- [Homebrew](install/homebrew.md)
+- [Homebrew](#homebrew)
 - [MacPorts](https://ports.macports.org/port/libiio/)
-- DMG installer from the [GitHub releases page](ttps://github.com/analogdevicesinc/libiio/releases)
+- DMG installer from the [GitHub releases page](https://github.com/analogdevicesinc/libiio/releases)
 - [Building from source](install/source.md)
-
-
diff --git a/docs/source/install/source.md b/docs/source/install/source.md
@@ -12,7 +12,7 @@ git checkout v0.25
 
 This section describes how to build libIIO from source. This is useful if you want to use the latest features or if you are developing libIIO itself.
 
-### Install Prerequisites/Dependencies and Build
+## Install Prerequisites/Dependencies and Build
 
 ````{tab} Linux (Debian/Ubuntu)
 
@@ -125,7 +125,8 @@ This process relies on [Homebrew](https://brew.sh/), a package manager for macOS
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```
 
-### Easy: Using a homebrew formula
+(homebrew)=
+### Easy: Using a homebrew formula 
 
 ```shell
 brew install tfcollins/libiio
@@ -165,7 +166,7 @@ sudo make install
 
 ---
 
-
+(configuration-options)=
 ## Configuration Options
 
 when configuring libiio with cmake, there are a few optional settings that you can use to control the build.

diff --git a/docs/source/landing.md b/docs/source/landing.md
diff --git a/docs/source/related.md b/docs/source/related.md
@@ -1,13 +1,12 @@
 # Related Projects
 
-- [IIO-Oscilloscope]()
-- [pyadi-iio]()
+- [IIO-Oscilloscope](https://wiki.analog.com/resources/tools-software/linux-software/iio_oscilloscope)
+- [pyadi-iio](https://analogdevicesinc.github.io/pyadi-iio/)
 - MATLAB Toolboxes
-  - [Analog Devices Transceiver Toolbox]()
-  - [Analog Devices High Speed Converter Toolbox]()
-  - [Analog Devices RF and Microwave Toolbox]()
-  - [Analog Devices Precision Toolbox]()
-- [Scopy]()
-- [libad9361-iio]()
-- [libad9166-iio]()
-- [iio-emu]()
+  - [Analog Devices Transceiver Toolbox](https://analogdevicesinc.github.io/TransceiverToolbox/master/)
+  - [Analog Devices High Speed Converter Toolbox](https://analogdevicesinc.github.io/HighSpeedConverterToolbox/master/)
+  - [Analog Devices RF and Microwave Toolbox](https://analogdevicesinc.github.io/RFMicrowaveToolbox/master/)
+  - [Analog Devices Precision Toolbox](https://analogdevicesinc.github.io/PrecisionToolbox/)
+- [Scopy](https://wiki.analog.com/university/tools/m2k/scopy)
+- [libad9361-iio](https://analogdevicesinc.github.io/libad9361-iio)
+- [libad9166-iio](https://analogdevicesinc.github.io/libad9166-iio)