The Build Package step “compiles” JavaScript and SASS, fetches third-party
+assets and licenses and generates the Python package.
+
Then, in the middle-stage, two parallel runs are launched:
+
+
Build Doc Latest: uses the latest stable dependencies releases to
+generate this documentation, and store as an artifact.
+
Build Doc on Min: uses the minimum requirements dependencies to generate
+this documentation, but the output is discarded.
+
Tests: run tests using pytest, in special, methods that are not called
+during the Build Doc * pipelines.
+
+
Both of them are set to fail-on-warning during the documentation generation.
+
Finally, the Deploy Package:
+
+
Grabs the version and checks if the tag version already exists:
+
+
If so, set to update the symbolic pre-release release.
+
If not, set to update the symbolic latest and pre-relase release.
+
+
+
Still if a new version:
+
+
Create the git tag and push to origin.
+
Create the tagged release.
+
Upload the artifact to the tagged release.
+
+
+
Upload the artifact to the symbolic release (pre-release, latest).
+
Finally, the Build Doc Latest artifact is downloaded and deployed to the
+branch gh-pages
+
+
By design, the live page on github.io follows the pre-release/latest commit-ish;
+properly versioned live documentation should be managed by an external system
+that watches the git tags (e.g.
+readthedocs).
+
This approach allows to have a single defined version on adi_doctools/__init__.py,
+and have the tags created and releases created/updated without much fuzz.
+
The philosophy is to have latest updated on tag increment and first
+successful run, and pre-relese updated on successful run without tag change.
+These releases exist to provide a pointer to the latest/pre-release packages, e.g.
+releases/download/latest/adi-doctools.tar.gz.
+
Non-handled corner-cases mitigations:
+
+
Release pre-release and latest must exist prior the first run.
+
Branch gh-pages must exist with at least one commit.
+
+
+
+
Documentation build and deployment
+
Doctools is developed to work offline, in a local server, as a rolling release
+(e.g. on GitHub Page)s and versioned in a dedicated server (with orchestration).
+
+
Local
+
For offline and local server, a makehtml suffice to generate the
+documentation.
+
To serve the build in a local server, Python built-in server can be used:
With the Sphinx -W flag, Sphinx exits with an error if any warning is logged,
+and --keep-going continues the build even if a warning is logged, to provide
+a complete log for analysis.
+
The deploy-doc job only runs when push/merged to main.
+
+
Attention
+
GITHUB_SHA on pull_request is the pre-commit and not the head commit,
+please be aware of GitHub events values if implementing something else.
The live versioned version requires additional orchestration than the
+Rolling release.
+Store each version in separated folders in the root path, e.g.
+v1.1, v2.2, main, dev and generate a tags.json
+containing a plain array with each version on the root path,
+e.g. ["v1.1","v2.2","main","dev"]
+(a empty string means there is a built doc on the root).
+This tags.json is used solely by the opened live page to show a dropdown to
+switch between versions.
For In organization reference, the doc shall target a specific version by suffixing
+the target the version on the interref_repos variable, e.g.
+interref_repos=['pyadi-iio/dev','other-repo/v1.1'].
If you don’t want to install npm, use Serve and accept the prompt to
+fetch the pre-built web-scripts from the latest release.
+
+
+
Why is the Python source code of this repo not watched?
+
Since a Python scripts change would affect rebuilding the whole documentation,
+those files are not watched by design even with the --dev option.
+Extensions at the doc itself are, however.
+
Alternatively, touch the source doc of the open page to rebuild only it
+with the edited Python code.
+
+
+
Why was Author Mode renamed to Serve?
+
Solely to match other tools like mkdocsserve, webpackserve,
+npmrunstart, hugoserver,
+
+
+
+
Custom Doc
+
Generates custom documents with filtered content from all documentations of the
+watched repositories (see adi_doctools/lut.py).
+
For PDF output, WeasyPrint is used (ensure to install it).
+
To quick start, run the tool twice in an empty directly.
+
~$
+
+
+
cd/tmp/my_doc
+
+
+
/tmp/my_doc$
+
+
+
adoccustom-doc
+
+
+
Configuration file doc.yaml not found, created template at:
+/tmp/my_doc/doc.yaml
+Update it with the desired sources and rerun the tool.
+
+
+
/tmp/my_doc$
+
+
+
adoccustom-doc--builderpdf
+
+
+
[ build output ]
+
+
+
The doc.yaml file is a concise human readable markup file to set the desired
+content and some other options.
+Running the tool in a directory without the doc.yaml will instantiate a template
+and return.
+If the necessary repositories are not found, the tool will clone for you.
+
In general, you can first clone and checkout your current work and then run the tool,
+to build the doc with your own changes.
+
Some documentations depend on auto generated sections and extra features, use
+the --extra option to enable those; it considers that the environment has all
+the tools needed, for example, vivado is accessible for the HDL documentation.
+See adi_doctools/cli/custom-doc.py to understand how the extra steps are
+included, but in summary, they are just a sequence of bash commands wrapped on python.
+
For all options, do:
+
~$
+
+
+
adoccustom-doc--help
+
+
+
Here is a minimal doc.yaml:
+
project:Custom user guide
+description:Subtitle of the user guide
+
+include:
+-documentation/software/libiio/cli.rst
+
+custom:
+-custom-pages/index.rst
+
+entry-point:
+-caption:My custom index
+files:
+-custom-pages/index.rst
+
+config:
+documentation:
+branch:"my-branch"
+
+extensions:
+-sphinx.ext.duration
+
+
+
The include option contains the list of files to include in the custom
+document, with the first level of the path the repository name.
+
During generation, the tool will resolve the hierarchy of the included docs,
+adding pages until the repository top-level page is reached.
+This may result in unwanted content being added and empty “category” sections.
+
To resolve that, it is possible to create custom top-level toctrees with the
+entry-point option.
+In summary, this:
Additional configuration can be added to the config option:
+
+
branch: Clone the repository from a specific branch, overwrite “main”.
+If the repository is already present, this option has no effect.
+
extra: Do steps that require extra software, for example, some vendor SDK.
+
+
The option extensions allow to append extra Sphinx extensions, beyond the
+automatically imported from the sourced documentations.
+
+
+
Aggregate
+
+
Tip
+
This feature is useful to batch build/test all tracked documentations.
+
+
Generates all documentations of the watched repositories
+(see adi_doctools/lut.py).
+
Two generation strategies are available:
+
+
monolithic: patches all docs together into a single monolithic output (default).
+
symbolic: generate each doc independently, just save them together (--symbolic).
+
+
For the monolithic output, do:
+
/tmp/all-docs$
+
+
+
adocaggregate
+
+
+
Some documentations depend on auto generated sections and extra features, use
+the --extra option to enable those; it considers that the environment has all
+the tools needed, for example, vivado is accessible for the HDL documentation.
+See adi_doctools/cli/aggregate.py to understand how the extra steps are
+included, but in summary, they are just a sequence of bash commands wrapped on python.
+
For all options, do:
+
~$
+
+
+
adocaggregate--help
+
+
+
+
+
HDL Render
+
Exposes the HDL component diagram generator as a CLI.
+It converts IP-XACT files into SVGs.
+
To generate and open the diagram, provide the path containing the IP-XACT and use
+the --open option:
The list-tables parameter requires pandoc-types >= 1.23, included in any
+recent pandoc release;
+if it is not an option, you shall remove it and export in the grid table
+format (see Tables for more information).
+
After converting, update it to better conform with the guidelines below, and
+make sure to use our directives and roles, for example, the Git role.
Directives are indented with 3 space, which is Sphinx’s default.
+At code directives, the code keeps its original indentation (e.g. 2 spaces for
+Verilog code), but is offset by 3 spaces at the beginning of every line, to
+instruct Sphinx the beginning and end of the code directive.
+
+
+
Table of contents
+
The relation between pages are created with the toctree directive,
+which allows to generate the table of contents and navigation bars.
+
Each page may have only one toctree, since they are the equivalent of the
+volumes of a book, and it does not make sense to have multiple “volumes” at
+the repository level.
+
The only exception is the ADI System Level Documentation repository, which indeed contains various
+types of documentation (eval-boards, university program, Linux drivers, etc.).
+
The toctree directive has the following format:
+
..toctree::
+ :maxdepth:<depth>
+
+ Custom title <path/to/page>
+
+
+
For pages with shorter titles, such as libraries, the label is inherited from
+the page itself, for example:
This way, only “AD7616-SDZ” will be displayed in the page navigation bar instead
+of “AD7616-SDZ HDL project”.
+
Also, it is recommended to wrap the toctree in a “Contents” section:
+
Contents
+========
+
+..toctree::
+
+ some_page
+
+
+
For extensive documentation with different topics, it makes sense to filter
+the toctree based on the current topic/toctree title.
+This is possible by setting the environment variable ADOC_FILTER_TOCTREE to
+1.
+Alternatively, setting filter_toctree on conf.py has higher precedence
+than ADOC_FILTER_TOCTREE.
+And is supposed to be used alongside the topic field at lut.py to
+preserve high level links for each topic.
+
Enable this environment variable only on the release build, since writing pages
+with it enabled may be obnoxious and confusing prior the final structure/location
+of them.
+
+
+
Versioning
+
To avoid having the version set in multiple places or having to tweak conf.py
+to obtain it from somewhere else, continuous integration can set the environment
+variable ADOC_DOC_VERSION to set the version value.
+
Still, the version value on conf.py has higher precedence, and
+ADOC_DOC_VERSION will be ignored if the variable is already set.
+
The CI, in general, should set ADOC_DOC_VERSION as the current checkout branch
+in the pipeline (e.g. main, v1.0.0).
+
+
Tip
+
If creating a branch or PR output, consider using GitHub short reference
+${{github.ref_name}}.
+
+
If both environment variable and version on conf.py are unset, it defaults
+to an empty string.
+
Also, set ADOC_TARGET_DEPTH to match the final destination depth, for example,
+if the target directory is:
+
+
./: 0 or unset
+
./v2.2: 1
+
./prs/1234: 2
+
./staging/user/branch: 3
+
+
+
+
Exporting to PDF
+
The whole documentation can be exported to a PDF document for a more compact
+format using either rs2pdf or WeasyPrint.
+This is done by setting the environment variable called
+ADOC_MEDIA_PRINT (the value does not matter) and building the documentation.
+
For rst2pdf, use:
+
sphinx-build -b pdf . _build/pdfbuild
+
+
+
In the output folder, you’ll find a PDF document named after the repository
+(e.g. Doctools.pdf). This document includes an auto-generated cover, followed by
+the remaining pages. Note that an HTML build of the documentation is not
+required for the PDF build.
+
+
Warning
+
The enviroment variable ADOC_MEDIA_PRINT should be unset when building
+the HTML pages of documentation. If not set, some components of the pages
+may not render properly.
The advantage of WeasyPrint is that the design styles (CSS stylesheet) is
+respected.
+
+
Inner working
+
Internally, ADOC_MEDIA_PRINT variable is set to app.config.media_print
+and should be used in scenarios where it is explicitly needed to compile the
+content in a different manner than for the hosted html.
+For example, to render content during build that would instead be rendered with
+third-party JavaScript libraries in the user browser.
References to labels have the format :ref:`contexttopic`, e.g.
+:ref:`rolegit` renders as Git role.
+
Labels are created for any content with the syntax
+(dot-dot underscore<label>two-dots):
+
.._context topic:
+
+
+
+
Hint
+
Add labels to any content that may be linked, locally or
+externally.
+
+
References to docs have the format :doc:`path/to/doc`, e.g.
+:doc:`docs_guidelines` for docs_guidelines.rst.
+
+
Attention
+
Do not break reference roles between lines!
+Even though Sphinx allows breaking line inside the reference role,
+it makes pattern matching hard.
+
+
Prefer hyphen separation - over undeline _ for the “title” section,
+and always lower case,
+for example
+my_codecontrol-interface instead of MY_CODEControl_Interface.
+
+
Numbered references
+
References can be numbered by using
+numref,
+for example, “see Figure 1”.
By default enumeration is global, so if the toctree is not
+numbered to divide the pages in numbered sections (e.g. Figure 3.4.4),
+the numbering will “propagate” across page which may be counter-intuitive.
+
To have the numbering reset at every page, add numfig_per_doc=True to
+conf.py.
+
+
+
+
+
External references
+
External references to other Sphinx documentation are created using the built-in
+sphinx.ext.intersphinx extension.
+
To setup in-organization references read the section below,
+and for third-party docs, the section that follows.
+
+
For either, to create a reference to a label, use:
+
:external+inv:ref:`label`, where inv is a mapped source,
+for example, :external+hdl:ref:`spi_enginecontrol-interface`.
+
+
+
To create a reference to a doc, use:
+
:external+inv:doc:`label`, where inv is a mapped source,
+for example, :external+hdl:doc:`library/spi_engine/index`.
+
+
As the other roles, it is possible to customize the text, e.g.
+:external+hdl:ref:`Customtext<spi_enginecontrol-interface>`.
+
+
Tip
+
Pay attention to the log output, since
+a warnings is thrown for each reference not found.
+
+
External references work with any kind of references, such as
+ref, doc, envvar, token, term, numref and keyword.
+
+
For references to labels it is possible to use the short form:
+
:ref-inv:`label` (equivalent to :external+inv:ref:`label`),
+but is discouraged.
+
+
+
Note
+
Sphinx 8 allows the syntax :ref:`<inv>:label`,
+which allows local references to have higher precedence than external
+refs, useful for generating custom docs like user guides.
+However, since some users may require Sphinx 7, use the former syntax,
+and let adoc patch it when necessary.
+
+
To show all links of an InterSphinx mapping file, use the built-in tool:
To create references to Sphinx docs inside the organization add the repositories
+of interest to the conf.py file with the following format:
+
interref_repos=[external...]
+
+
+
For example:
+
interref_repos=['hdl','no-OS','pyadi-iio/main']
+
+
+
Notice that in the example main suffixes pyadi-iio, this means that will
+look for the build at path main of this repo instead of at root.
+This can be used to target a specific version, if the target repository stores
+multiple, for example, v1.1, more about that Versioned.
It is possible to customize the target URL with the interref_uri config or
+ADOC_INTERREF_URI environment variables.
+The default value is https://analogdevicesinc.github.io/ and can be set to a
+local path like ../../.
+
Beyond the main target dictated by interref_uri,
+by setting the config interref_local as true, a secondary target is inferred
+foreseeing a local copy of the target external documentation alongside the
+current repository:
Each line must be less than 80 columns wide.
+You can use the fold command to break the lines of the imported text
+while respecting word-breaks:
+
catimported.txt|fold-sw80>imported.rst
+
+
+
The header divider “---” shall be either 80 characters wide or end at the
+title character, that means, this is also valid:
+
Mytitle
+========
+
+
+
+
+
Tables
+
Prefer
+list-tables
+and imported
+csv-tables
+(using the file option), because they are faster to create, easier to maintain
+and the 80 column-width rule can be respected with list-tables.
+
Only use
+grid tables
+if strictly necessary, since they are hard to update.
+
To tune styling, the following classes are available:
+
+
bold-header: Make the header bold.
+
bold-first-column: Make the first column bold.
+
+
+
+
Lists
+
Unordered lists use * or - and ordered lists #..
+
Child items must be aligned with the first letter of the parent item, that means,
+2 spaces for unordered list and 3 spaces for ordered lists, for example:
In general, this avoids dangling artifacts and keeps the documentation simple.
+
+
+
Git Large File Storage
+
Where applicable, Git Large File Storage (LFS) is used to replace large files
+with text pointers inside Git, reducing cloning time.
+
To setup, install from your package manager and init:
+
aptinstallgit-lfs
+gitlfsinstall
+
+
+
The files that will use Git LFS are tracked at .gitattributes, to add new
+files use a pattern at the repo root, for example:
+
gitlfstrack*.jpg
+
+
+
Or edit .gitattributes directly.
+
+
+
Third-party directives and roles
+
Third-party tools are used to expand Sphinx functionality, if you haven’t already,
+do:
+
pipinstall-rrequirements.txt
+
+
+
+
+
Custom directives and roles
+
To expand Sphinx functionality beyond existing tools, custom directives and roles
+have been written, which are located in the docs/extensions folder.
+Extensions are straight forward to create, if some functionality is missing,
+consider requesting or creating one.
+
+
Note
+
Link-like roles use the :role:`text<link>` synthax, like external
+links, but without the undescore in the end.
+
+
+
Color role
+
To print text in red or green, use :red:`text` and :green:`text`.
+
+
+
Link roles
+
The link roles are a group of roles defined by adi_links.py.
+
The validate_links global option is used to validate each link during build.
+These links are not managed, that means, only links from changed files are checked.
+You can run a build with it set to False, then touch the desired files to check
+the links of only these files.
+
+
Git role
+
The Git role allows to create links to the Git repository with a shorter syntax.
+The role syntax is :git-repo:`text<type+branch:path>`, for example:
When the branch field is not present, it will be filled with the current branch.
+It is recommended to not provide this field when it is a link to its own repository,
+because it is useful to auto-fill it for documentation releases
+(e.g. hdl_2023_r2).
+A scenario where it is recommended to provide the branch is when linking others
+repositories.
+
They type field is also optional and the values are:
+
+
gui: To view rendered on the Git server web GUI [default].
+
raw: To download/view as raw.
+
{}: Any other Git server web GUI link, e.g. :git-hdl:`releases+`.
+The last character must be +, since filenames/path may contain this character
+also.
+
+
The text field is optional and will be filled with the full path.
+
Finally, you can do :git-repo:`/` for a link to the root of the
+repository with pretty naming, for example, :git-hdl:`/` is rendered
+as ADI HDL repository.
The adi role creates links for a webpage to the Analog Devices Inc. website.
+
The role syntax is :adi:`text<webpage>`, for example,
+:adi:`AD7175-2<ad7175-2>`.
+Since links are case insensitive, you can also reduce it to
+:adi:`AD7175-2`, when webpage is the same as text and will render
+as AD7175-2.
+
+
+
Dokuwiki role
+
The dokuwiki role creates links to the Analog Devices Inc. wiki website.
+The role syntax is :dokuwiki:`text<path>`, for example,
+:dokuwiki:`pulsar-adc-pmods<resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>`
+gets rendered as
+pulsar-adc-pmods.
+
For intentional deprecated links, add the deprecated qualifier, e.g.:
+:dokuwiki+deprecated:`ADS-BAirplaneTrackingExample<resources/tools-software/linux-software/libiio/clients/adsb_example>`
+gets rendered as
+ADS-B Airplane Tracking Example.
+The sole intend of this qualifier is to distinct pending import pages from won’t
+import pages.
+
+
+
EngineerZone role
+
The ez role creates links to the Analog Devices Inc. EngineerZone support website.
+The role syntax is :ez:`community`, for example, :ez:`fpga`
+gets rendered as EngineerZone.
+
For Linux Software Drivers, it is :ez:`linux-software-drivers`.
+
For Microcontroller no-OS Drivers it is :ez:`microcontroller-no-os-drivers`.
+
+
+
Vendor role
+
The vendor role creates links to the vendor’s website.
+The role syntax is :vendor:`text<path>`, for example,
+:xilinx:`Zynq-7000SoCOverview<support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>`
+gets rendered
+Zynq-7000 SoC Overview.
+
The text parameter is optional, if absent, the file name will be used as the text,
+for example,
+:intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html`
+gets rendered
+general-purpose-i-o-overview.html
+(not very readable).
The supplier role creates links to a vendor’s website search.
+The role syntax is :vendor:`text<path>`, for example,
+:digikey:`AD9081-FMCA-EBZ`
+gets rendered
+AD9081-FMCA-EBZ.
+
The text parameter is optional.
+
Supported vendors are: digikey (Digikey), mouser (Mouser) and
+arrow (Arrow).
+
+
+
+
Container directives
+
To allow disposing content in a tabular manner but still respecting the multiple
+screen sizes and both HTML and PDF output, two container directives are available,
+flex and grid.
+
+
Flex directive
+
The grid directive implements a subset of
+CSS Flex.
+And is used to dipose elements without worrying about number of columns and sizes,
+while still obtaining a fairly good result.
+
..flex::
+
+
+
+
+
Grid directive
+
The grid directive implements a subset of
+CSS Grids.
+And is used to dipose elements with exact number of columns and width control.
+
..grid::
+ :widths: 25 25% 150px
+
+
+
The widths options allow units (px, %, etc) and without an explicit
+unit it is inferred percentile.
+This option is required, since it is not possible to infer the number of
+columns in a sane manner.
+
+
+
+
Clear content directive
+
A simple directive to
+clear
+the content, forcing any following content to be moved below any preceding
+content.
+It is useful when working with images
+aligned/float
+left/right and wants to ensure the next section does not also gets “squashed”.
That means, each line is prefixed by character to:
+
+
$: bash commands.
+
(one space): command output.
+
#: bash comments
+
/: set absolute working directory (cygpath-formatted for ps1).
+
~: set relative to “home” working directory (cygpath-formatted for ps1).
+
+
Anything that does not match the previous characters will default to output print,
+but please be careful, since you may accidentally mark a working directory or
+command, if not identing the output by one space.
+
The bash type defaults to bash, user to user, group to analog
+and the working directory as “doesn’t matter” (hidden), so, for
+example:
[sudo] password for user:
+0+60640 records in 0+60640 records out 7948206080 bytes (7.9 GB) copied, 571.766 s, 13.9 MB/s
+real 7m54.11s user 0.29s sys 8.94s
+
+
+
+
+
HDL build status directive
+
The HDL build status directive gets information from a markdown formatted status
+table (output.md) and generates a table with the build statuses.
The :path: option is optional, in the sense that if it’s not provided, no table
+is generated.
+If provided, but the build status file does not exist, an error is
+thrown.
+
+
Note
+
The :path: option is meant to be “filled” during a CI procedure.
+
+
+
+
HDL parameters directive
+
The HDL parameters directive gets information parsed from IP-XACT (component.xml)
+library and generates a table with the IP parameters.
+
+
Note
+
The IP-XACT files are generated by Vivado during the library build and not by
+the documentation tooling.
..hdl-parameters::
+ :path: library/spi_engine/spi_engine_interconnect
+
+ * - DATA_WIDTH
+ - Data width of the parallel SDI/SDO data interfaces.
+ * - NUM_OF_SDI
+ - Number of SDI lines on the physical SPI interface.
+
+
+
Descriptions in the directive have higher precedence than in the component.xml
+file.
+
The :path: option is optional, and should not be included if the
+documentation file path matches the component.xml hierarchically.
+
+
+
HDL interface directive
+
The HDL interfaces directive gets information parsed from component.xml library
+and generates tables with the IP interfaces, both buses and ports.
+
+
Note
+
The component.xml files are generated by Vivado during the library build
+and not by the documentation tooling.
Descriptions in the directive have higher precedence than in the component.xml
+file.
+You can provide description to a port or a bus, but not for a bus port.
+Ports/buses that are consecutive are squashed into a single instance
+to avoid repetition, for example:
To provide a description to the squashed signals/buses, write, for example,
+data_tx_* once instead of the original name of all.
+
+
Warning
+
Do not create new IP with signals named as _phy*, it was added for
+legacy puporses, instead suffix with _*, e.g. mysignal_phy_4.
+
+
The :path: option is optional, and should not be included if the
+documentation file path matches the component.xml hierarchically.
+
+
+
HDL component diagram directive
+
The HDL component diagram directive gets information parsed from component.xml
+library and generates a component diagram for the IP with buses and ports
+information.
+
+
Note
+
The component.xml files are generated by Vivado during the library build
+and not by the documentation tooling.
The register map name is the title-tool, the value above ENDTITLE in the
+source file.
+
+
This directive does not support content for descriptions, since the source file
+already have proper descriptions.
+
The :name: option is required, because the title tool does not match
+the IP name and one single docs/regmap/adi_regmap_*.txt file can have more than
+one register map.
+The :no-type-info: option is optional, and should not be included if it is
+in the main IP documentation page. It appends an auxiliary table explaining the
+register access types.
+
+
+
Collapsible directive
+
The collapsible directive creates a collapsible/dropdown/”HTML details”.
Notice how you can use any Sphinx syntax, even nest other directives.
+
+
+
Video directive
+
The video directive creates a embedded video.
+Currently, direct MP4 and youtube embed links are supported, but could be easily
+expanded to support third-party services.
..video:: https://www.youtube.com/watch?v=p_VntEwUe24
+
+ **LibIIO - A Library for Interfacing with Linux IIO Devices** - Dan Nechita, Analog Devices Inc
+
+
+
Renders as:
+
LibIIO - A Library for Interfacing with Linux IIO Devices - Dan Nechita, Analog Devices Inc
+
Video
+
LibIIO - A Library for Interfacing with Linux IIO Devices - Dan Nechita, Analog Devices Inc
The ESD warning directive creates a ESD warning, for example:
+
..esd-warning::
+
+
+
Renders as:
+
+
All the products described on this page include ESD (electrostatic discharge) sensitive devices. Electrostatic charges as high as 4000V readily accumulate on the human body or test equipment and can discharge without detection.
+Although the boards feature ESD protection circuitry, permanent damage may occur on devices subjected to high-energy electrostatic discharges. Therefore, proper ESD precautions are recommended to avoid performance degradation or loss of functionality. This includes removing static charge on external equipment, cables, or antennas before connecting to the device.
+
+
+
+
Global options for directives
+
Set hide_collapsible_content to True to hide the collapsibles by default.
+
Set monolithic to True prefix paths with <repo>.
+This is meant for the Custom Doc custom documents only.
+
+
+
Common sections
+
+
HDL common sections
+
The More information and Support sections that are present in
+the HDL project documentation, are actually separate pages inserted as links.
+They’re located at hdl/projects/common/more_information.rst and /support.rst,
+and cannot be referenced here because they don’t have an ID at the beginning
+of the page, so not to have warnings when the documentation is rendered that
+they’re not included in any toctree.
Dynamic elements refer to sections of the generated webpage that updates when
+loaded online from a source of truth, in general, doctools/*.json files;
+it uses a concept similar to “react components”.
+
These *.json files are generated when export_metadata is true in the
+conf.py.
+From the JavaScript side, it fetches from
+{content_root}[../versioned]/../doctools/[versioned]/metadata.json.
+
+
Note
+
path version is present and set if latest exists at
+{content_root}/../doctools and the stored version can be extracted.
+
+
The dynamic elements are:
+
+
The navigation bar at the top is updated using the repotoc entry
+in doctools/metadata.json.
+
A banner at the top is present/updated when the banner entry
+in doctools/metadata.json exists.
Doctools is the central piece to aggregate multiple documentations together,
+expanding the documentation standard hierarchical, mono-repo configuration.
+The content is organized in three levels:
+
+
repotoc: Listing of repositories in the same organization that contain
+documentations.
+In general, a repository contains only one topic (toctree), e.g. the pyadi-iio
+doc is only about the libiio python bindings.
+If a repo stores more than one toctree/topic, the topic attribute is used to
+split each toctree on its own repotoc entry, as if they were stored in multiple
+repositories.
+The topic entry must contain one landing page associated with the toctree title,
+e.g. topic:{'eval':'EvaluationBoards','university':'UniversityProgram'},
+then the index.rst must a toctree titled EvaluationBoards and the page
+eval/index.rst must exist.
+In the html output, is displayed on the top header.
+
toc: Table of contents of a repository documentation; the displayed depth
+is customizable, but in general a doc page (.rst, .md) generates one toc
+entry.
+In the html output, is displayed on the left of the webpage.
+
localtoc: Contents on the current doc page/toc entry.
+In the html output, is displayed on the right of the webpage, identified by the
+“On this page” header.
+
+
+
Note
+
The repotoc is managed by the adi_doctools/lut.py and is
+not a native Sphinx feature.
+toc and localtoc are concepts inherited from Sphinx.
+
+
By the concept of repotoc, it is possible to each doc to reference other
+repository doc using the In organization reference role.
Install the documentation tools, which will fetch this repository release:
+
~$
+
+
+
(cddocs;pipinstall-rrequirements.txt)
+
+
+
Test it building this documentation:
+
~$
+
+
+
(cddocs;makehtml)
+
+
+
+
+
Using a Python virtual environment
+
Installing packages at user level through pip is not always recommended, instead,
+consider using a Python virtual environment (python3-venv on ubuntu 22.04).
+
To create and activate the environment, do before the previous instructions:
+
~$
+
+
+
python3-mvenv./venv
+
+
+
~$
+
+
+
source./venv/bin/activate
+
+
+
Use deactivate to exit the virtual environment.
+
For next builds, just activate the virtual environment:
+
~$
+
+
+
source./venv/bin/activate
+
+
+
+
+
+
Development install
+
Development install allows to edit the source code and apply the changes without
+reinstalling.
+Also extends Author Mode to watch changes on the webpage source code
+(use –dev/-r option to enable this).
+
+
Install the web compiler
+
If you care about the web scripts (js modules) and style sheets (sass),
+install npm and the npm packages below, if not, read this section’s
+last paragraph.
+
+
Note
+
If the npm provided by your package manager is too old and updating with
+npminstallnpm-g fails, consider installing with
+NodeSource.
+
+
At the repository root, install the npm dependencies locally:
If you choose to not use npm, you can obtain pre-built web-scripts from the
+latest release.
+For that, just run Why was Author Mode renamed to Serve? after the repository is installed and
+confirm the prompt that will appear.
A Sphinx themed called harmonic (old cosmic) is available.
+It is deeply based on ADI’s harmonic design language.
+
+
Shortcuts
+
Alt+Shift+ArrowLeft goes to the previous page and Alt+Shift+ArrowRight
+to the next page.
+Ctrl+Alt+Shift+ArrowLeft/Right preserves the current page anchor, for example,
+if the current section is project_0.html#details, Ctrl+Alt+Shift+ArrowRight
+goes to project_1.html#details, even if details does not exist.
+This feature is useful for batch reviewing sections common to multiple pages,
+e.g. “Supported Devices”.