Bulk updates for doc pages

Signed-off-by: Travis F. Collins <travis.collins@analog.com>
analogdevicesinc · Aug 21, 2024 · 5cbc410 · 5cbc410
1 parent d5a3b61
commit 5cbc410
Show file tree

Hide file tree

Showing 22 changed files with 2,067 additions and 4 deletions.
diff --git a/docs/requirements_doc.txt b/docs/requirements_doc.txt
@@ -2,4 +2,5 @@ sphinx
 https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz
 sphinxcontrib.wavedrom
 myst-parser
-breathe
+breathe
+sphinx-inline-tabs
diff --git a/docs/source/_static/codemodel.svg b/docs/source/_static/codemodel.svg
diff --git a/docs/source/_static/libiio_commands.png b/docs/source/_static/libiio_commands.png
diff --git a/docs/source/_static/libiio_details_readbuf.png b/docs/source/_static/libiio_details_readbuf.png
diff --git a/docs/source/_static/libiio_farview.png b/docs/source/_static/libiio_farview.png
diff --git a/docs/source/_static/libiio_highspeed_interface.png b/docs/source/_static/libiio_highspeed_interface.png
diff --git a/docs/source/_static/libiio_lowspeed_interface.png b/docs/source/_static/libiio_lowspeed_interface.png
diff --git a/docs/source/_static/libiio_open_command.png b/docs/source/_static/libiio_open_command.png
diff --git a/docs/source/_static/libiio_readbuf_command.png b/docs/source/_static/libiio_readbuf_command.png
diff --git a/docs/source/_static/libiio_route_highspeed.png b/docs/source/_static/libiio_route_highspeed.png
diff --git a/docs/source/_static/libiio_route_lowspeed.png b/docs/source/_static/libiio_route_lowspeed.png
diff --git a/docs/source/_static/libiio_route_zerocopy.png b/docs/source/_static/libiio_route_zerocopy.png
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,9 +1,12 @@
 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
-    :caption: C API
 
     api/c/top
     api/c/scan

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -26,13 +26,14 @@
     "myst_parser",
     "breathe",
     'sphinxcontrib.matlab', 'sphinx.ext.autodoc',
+    "sphinx_inline_tabs",
 ]
 
 needs_extensions = {
     'adi_doctools': '0.3.6'
 }
 
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = ["colon_fence", "attrs_inline"]
 
 breathe_default_project = "libiio"
 breathe_projects = {"libiio": os.path.join(doxyfolder, "generated", "xml")}

diff --git a/docs/source/examples.md b/docs/source/examples.md
@@ -1,2 +1,71 @@
 # 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.
+
+:::{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.
+:::
+
+## Connect to Ethernet Context and List Devices
+
+```c
+#include <stdio.h>
+#include <iio.h>
+
+int main() {
+
+    struct iio_context *ctx;
+    struct iio_device *dev;
+    struct iio_device **devices;
+    int i, ndevices;
+
+    ctx = iio_create_context(NULL, "ip:analog.local");
+    ndevices = iio_context_get_devices_count(ctx);
+    for (i = 0; i < ndevices; i++) {
+        dev = iio_context_get_device(ctx, i);
+        printf("Device %d: %s\n", i, iio_device_get_name(dev));
+    }
+
+    iio_context_destroy(ctx);
+
+    return 0;
+}
+```
+
+## Write Device and Channel Attribute
+
+```c
+
+#include <stdio.h>
+#include <iio.h>
+
+int main() {
+
+    struct iio_context *ctx;
+    struct iio_device *dev;
+    struct iio_channel *ch;
+    struct iio_attr *attr;
+
+    ctx = iio_create_context(NULL, "ip:analog.local");
+    dev = iio_context_find_device(ctx, "ad9361-phy");
+    attr = iio_device_find_attr(dev, "ensm_mode");
+    iio_attr_write(attr, "fdd");
+
+    ch = iio_device_find_channel(dev, "voltage0", false);
+    attr = iio_channel_find_attr(ch, "hardwaregain");
+    iio_attr_write(attr, "0");
+
+    iio_context_destroy(ctx);
+
+    return 0;
+}
+```
+
+## Device Specific Examples
+
+The following examples are available in the libiio repository:
+
+- [ad9361-iiostream.c](https://github.com/analogdevicesinc/libiio/blob/main/examples/ad9361-iiostream.c)
+- [ad9361-iio-stream.c](https://github.com/analogdevicesinc/libiio/blob/main/examples/ad93761-iiostream.c)
+- [adrv9002-iiostream.c](https://github.com/analogdevicesinc/libiio/blob/main/examples/adrv9002-iiostream.c)
+- [adrv9009-iiostream.c](https://github.com/analogdevicesinc/libiio/blob/main/examples/adrv9009-iiostream.c)
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -31,13 +31,22 @@ Once you have secured your access to the library and its header, please check th
 
 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
+
+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.
+
+Separately, the IIO Library also includes a set of test examples and utilities, (collectively known as iio-utils) which are developed and released under the terms of the GNU General Public License, version 2 or (at your option) any later version.
+
+The full terms of the library license can be found at: http://opensource.org/licenses/LGPL-2.1 and the iio-utils license can be found at: https://opensource.org/licenses/GPL-2.0
+
 # Project Pages
 
 ```{toctree}
 :maxdepth: 1
 
 install
 theory
+usage
 examples
 api
 bindings

diff --git a/docs/source/install.md b/docs/source/install.md
@@ -1,2 +1,47 @@
 # Installation
 
+It is recommended to use the latest releases through pre-built packages when available. If you need the latest features or are developing libIIO itself, you can build from source following guides:
+
+```{toctree}
+:maxdepth: 1
+
+install/source
+```
+
+## Installation Packages
+
+Pre-built packages are available for the following for a number of different platforms from GitHub as well as from different package managers.
+
+### Windows
+
+Install the latest release from the [GitHub releases page](https://github.com/analogdevicesinc/libiio/releases).
+
+The EXE installer is recommend but zip packages include the same files, which can be useful for developers.
+
+
+### Linux
+
+Most Linux users can install libIIO from their distribution's package manager. For example, on Ubuntu, you can install libIIO with the following command:
+
+```bash
+sudo apt-get install libiio0
+```
+
+It can be also useful to install the development package and tools:
+
+```bash
+sudo apt-get install libiio-dev libiio-utils
+```
+
+Please reference your OS's package manager for the correct package names. Alternatively, you can download the latest release from the [GitHub releases page](https://github.com/analogdevicesinc/libiio/releases) or build from source.
+
+### macOS
+
+For macOS there are four options:
+
+- [Homebrew](install/homebrew.md)
+- [MacPorts](https://ports.macports.org/port/libiio/)
+- DMG installer from the [GitHub releases page](ttps://github.com/analogdevicesinc/libiio/releases)
+- [Building from source](install/source.md)
+
+