Skip to content

Switch to sphinx doc #1196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Switch to sphinx doc #1196

wants to merge 3 commits into from

Conversation

@tfcollins
Copy link
Contributor

@tfcollins tfcollins commented Sep 9, 2024 •
edited
Loading

Move doc to sphinx

This PR switches doc to the new Sphinx flow followed by HDL, pyadi-iio, No-OS, and TransceiverToolbox. This includes:

  • API doc for C through Breathe and Python (sphinx-autodoc)
  • A number of wiki pages have been merged in on libiio's internals
  • Original technical doc used within the Doxygen builds
  • Build instructions (Windows, Linux, macOS)

There is still doc missing for:

  • C# bindings
  • Links to past revs
  • CI to deploy generated pages

PR Type

  • New feature (a change that adds new functionality)

PR Checklist

  • I have conducted a self-review of my own code changes
  • I have commented new code, particulary complex or unclear areas
  • I have checked that I did not intoduced new warnings or errors (CI output)
  • I have checked that components that use libiio did not get broken
  • I have updated the documentation accordingly (GitHub Pages, READMEs, etc)

@tfcollins
Remove old doxygen based doc
2667d3d 
Signed-off-by: Travis F. Collins <[email protected]>
@tfcollins tfcollins force-pushed the tfcollins/sphinx-doc branch 2 times, most recently from d13e96e to a1ba819 Compare September 10, 2024 16:19
@tfcollins
Add Sphinx doc and helper scripts
8430756 
Signed-off-by: Travis F. Collins <[email protected]>
@tfcollins
Add CI for sphinx doc builds
7ec2687 
Signed-off-by: Travis F. Collins <[email protected]>
@gastmaier
Copy link
Contributor

gastmaier commented Sep 10, 2024 •
edited
Loading

There is still doc missing for: Links to past revs

My idea is to track versions on gh-pages with a simple tags.json,
and implement the version dropdown selector on the sphinx theme, fetching this file from {global_root}/tags.json.
So I suggest creating one like this

[
  "v0.25",
  "v0.26",
  "main"
]

and keep the current landing page? or put main on root / ... for doctools I did that by creating an array with all doc versions, then git rm all, and finally restoring by git checkout every dirname from the array.

CI to deploy generated pages

https://analogdevicesinc.github.io/doctools/ci.html#rolling-release
https://analogdevicesinc.github.io/doctools/ci.html#versioned
with ADOC_TARGET_DEPTH=1 considering store paths like "main" and "v0.26"

@tfcollins
Copy link
Contributor Author

tfcollins commented Sep 11, 2024

ok I get the idea. The libiio doc isn't greenfield so I'll have to think about handling the older doc.

@rgetz
Copy link
Contributor

rgetz commented Sep 13, 2024

Also missing cpp bindings doc.

@rgetz
Copy link
Contributor

rgetz commented Oct 4, 2024

ok I get the idea. The libiio doc isn't greenfield so I'll have to think about handling the older doc.

since v0.x will be "old", I would just put it in a subdir manually for now...

@gastmaier
Copy link
Contributor

gastmaier commented Feb 26, 2025 •
edited
Loading

since v0.x will be "old", I would just put it in a subdir manually for now...

Agreed and then just list them similar to this following the extended version syntax:

  "master": ["main", "unstable"],
  "v1.0": ["v1.0", "pre-release"],
  "v0.25": ["v0.25", "latest"],
  "v0.24 ["v0.24", ""],
}

and the GUI will render a dropdown

image
This can be done manually, since libiio is not release so frequently

the landing page could redirect to main/master or preferred version

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="refresh" content="0; url=main/index.html" />
  </head>
</html>

But the most important is: is the sphinx-doc with breath as good as the doxygen? Are we missing features?
Testing on my side, I found it easier to navigate and the man pages links are not broken as in v0.25, and it actually looks good:

theory2.pdf

I got the following warnings when building locally

/mnt/wsl/data/repos/libiio-new-doc/doc/source/api/c/scan.rst:4: WARNING: doxygenfunction: Cannot find function "iio_scan" in doxygen xml output for project "libiio" from directory: /mnt/wsl/data/repos/libiio-new-doc/doc/source/../doxygen/generated/xml [docutils]
/mnt/wsl/data/repos/libiio-new-doc/doc/source/api/c/scan.rst:7: WARNING: doxygenfunction: Cannot find function "iio_scan_destroy" in doxygen xml output for project "libiio" from directory: /mnt/wsl/data/repos/libiio-new-doc/doc/source/../doxygen/generated/xml [docutils]
/mnt/wsl/data/repos/libiio-new-doc/doc/source/api/c/scan.rst:10: WARNING: doxygenfunction: Cannot find function "iio_scan_get_results_count" in doxygen xml output for project "libiio" from directory: /mnt/wsl/data/repos/libiio-new-doc/doc/source/../doxygen/generated/xml [docutils]
/mnt/wsl/data/repos/libiio-new-doc/doc/source/api/c/scan.rst:13: WARNING: doxygenfunction: Cannot find function "iio_scan_get_description" in doxygen xml output for project "libiio" from directory: /mnt/wsl/data/repos/libiio-new-doc/doc/source/../doxygen/generated/xml [docutils]
/mnt/wsl/data/repos/libiio-new-doc/doc/source/api/c/scan.rst:16: WARNING: doxygenfunction: Cannot find function "iio_scan_get_uri" in doxygen xml output for project "libiio" from directory: /mnt/wsl/data/repos/libiio-new-doc/doc/source/../doxygen/generated/xml [docutils]

Lastly, if it is missing features on doctools side just open an issue on doctools, for example, a way to create these links on the sidebar would be desirable, no?
image

The adi_ros2 team handled multiple documentation as follows:
Each submodule doc goes below the current version "humble", then, used the tags.json extended syntax to render as follows:

image

I also asked them to inject a 'submodule' variable to each submodule doc conf.py to help track that we are at a "nested" doc/repo, so I can restore functionality on this corner case

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cristina-suteu cristina-suteu Awaiting requested review from cristina-suteu cristina-suteu is a code owner

@dNechita dNechita Awaiting requested review from dNechita dNechita is a code owner

@mhennerich mhennerich Awaiting requested review from mhennerich mhennerich is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@tfcollins @gastmaier @rgetz