Skip to content
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.

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

Switch to sphinx doc #1196

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

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)

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
Signed-off-by: Travis F. Collins <[email protected]>
Signed-off-by: Travis F. Collins <[email protected]>
@gastmaier
Copy link

gastmaier commented Sep 10, 2024

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

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...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants