reference-designs/ad717x-ad411x: Ported documentation from wiki to git

[ericserban22]

• ported Wiki pages (interposer, ace, mcu projects)
• added landing page, prerequisites, user guides
• De10Nano quickstart to be completed when no-OS project is available

Type

• Documentation
• Bug fix
• New feature
• Continuous integration

Checklist

• I have performed a self-review of changes
• I have followed the guidelines:
  • https://analogdevicesinc.github.io/documentation/contributing/docs_guidelines.html
  • https://analogdevicesinc.github.io/doctools/docs_guidelines/index.html
  • https://analogdevicesinc.github.io/documentation/contributing/creating_new_pages.html#documentation-structure
• I have used the appropriate roles and directives:
  • https://analogdevicesinc.github.io/doctools/docs_guidelines/roles.html
  • https://analogdevicesinc.github.io/doctools/docs_guidelines/directives.html
• I ensured that binary data was committed to git lfs:
  • https://analogdevicesinc.github.io/documentation/contributing/creating_new_pages.html#adding-images-and-other-binary-files
• I have built the pages I edited or created, using either make html or adoc serve:
  • https://analogdevicesinc.github.io/doctools/cli.html#serve
• I have signed-off my commits and believe my contribution improves the repository.

[StancaPop]

The doc build fails.

[ericserban22]

Quickstart folder and pages for de10nano exist locally but weren't included in the commit because they will only be finished when the ad7606 no-os project becomes available. The commented sections in the files relate to this quickstart.

[StancaPop]

Quickstart folder and pages for de10nano exist locally but weren't included in the commit because they will only be finished when the ad7606 no-os project becomes available. The commented sections in the files relate to this quickstart.

ad7606? I think that's a typo. I suppose you meant something about ad717x?

[ericserban22]

Quickstart folder and pages for de10nano exist locally but weren't included in the commit because they will only be finished when the ad7606 no-os project becomes available. The commented sections in the files relate to this quickstart.

ad7606? I think that's a typo. I suppose you meant something about ad717x?

yes, i meant ad717x/ad411x :) i have been working with ad7606 as well today and it was on my mind, my bad.

[github-actions]

LLM review

This series ports the AD717x/AD411x evaluation board documentation
(interposer, ACE, and Renesas RL78G13 no-OS driver pages) from
wiki.analog.com to git, and adds a landing page, prerequisites, and user
guides.

run: 32483863402

584b3d4 - Content dropped while porting from DokuWiki

Diffing each ported page against its wiki.analog.com source shows two
"Downloads" sections and one tutorial step were silently dropped:

• interposer.rst lost the link to ad7176_2_evalboard.zip and the table
  describing its folder contents (Bit, DataCapture, Hdl, Microblaze,
  Software) — the page still tells the reader to run Bit/download.bit
  without saying where to get it.
• ad7175_mcu_driver.rst and ad7176_mcu_driver.rst both lost their
  "Downloads" section (generic + RL78G13 driver zips) and the "extract the
  lab files" tutorial step, which is why
  rl78g13_software_tutorial_without_applilet3_05.png ships unused in both
  pages.

All five zip files were confirmed to still exist on wiki.analog.com.

Broken link and missing family member

user-guide-ad717x.rst links the LT1962 LDO to en/products/ltc1962.html
(typo inherited from the wiki source); the real part/page is lt1962. Also,
index.rst/prerequisites.rst list the AD411x family without AD4113
(and its EVAL-AD4113SDZ board), which is documented in the
precision-converters-firmware AD717x/AD411x IIO application.

Orphaned prerequisites (sanity check)

prerequisites.rst's Renesas RL78G13 section contains a second, unheaded
Hardware/Software block (BeMicro SDK, Quartus II, Nios II EDS) that actually
belongs to a retired wiki page ("BeMicro FPGA Project for AD7176-2 with
Nios driver") which was correctly not ported here. Left in place it reads as
a requirement for a page that doesn't exist.

CI warnings (truncated in the log)

case.py/dangling.py flag more issues for this PR than shown in the CI
log, because GitHub caps annotations at 10 per job. Re-running locally shows
2 upper-case image filenames and 16 unreferenced images in
eval_ad717x/images/. Two of the unreferenced images map to the content
gaps above; the other 14 are leftovers from unrelated, unported wiki pages
(retired BeMicro/Nios II project, EVAL-AD7173-8ARDZ hardware guide) and can
be removed.

vale warnings for Renesas and Xilinx are style-guide/spelling noise
(brand names, not misspellings) and are left untouched.

Verification data

Fetched each source page from wiki.analog.com?do=export_raw and diffed it
against the corresponding .rst file. Confirmed the referenced zip
downloads and the AD4113/EVAL-AD4113SDZ datasheets/user-guides still exist
via wget --spider and the ADI PDF sitemap. The AD7175-2 datasheet PDF was
unavailable both from the doctools docling mirror (not yet converted) and
directly from analog.com (blocked by Akamai bot protection); device specs
were instead cross-checked against the DokuWiki source text. Rebuilt with
adoc serve --once --sparse solutions/reference-designs/eval_ad717x before
and after the fixes (same 5 pre-existing, unrelated warnings both times), and
re-ran case.py/dangling.py, which report zero issues under eval_ad717x/
after the fixes.

Suggested patches

Apply the suggested patches with:

cd path/to/repository
export GITHUB_TOKEN=ghp_***
apply-patches --repo=analogdevicesinc/documentation 32483863402

Install instructions

The following one-liner installs the script if not present already:

curl -fSsL "https://raw.githubusercontent.com/analogdevicesinc/doctools/refs/heads/main/ci/scripts/apply-patches.sh"      -o ~/.local/bin/apply-patches.sh &&   grep -q "/apply-patches.sh" ~/.bashrc || echo "source ~/.local/bin/apply-patches.sh" >> $_ ; . $_

More information at AI Usage.

[thorenscientific]

Hi @StancaPop , @ericserban22, I happened to see the notification for this and took a quick look, I'd gone over some projects like this in the past. At least some of the pages and examples here look like "legacy" - frozen in time code as zip files on the wiki pages, which look like they did not get translated to GitHub. (The LLM review picked up on that.) It would be a good idea to scrub through the current no-OS and see if these parts are there, along with their reference designs, and refer to them accordingly. But for these Renesas, Xilinx KC705, etc. designs, either get rid of them, or put a big warning at the top "For Reference Only" Also double check all of the links to outside sites - many are broken. Oh and the KC705 is also obsolete.

Note that the SDP-B and ACE based stuff can stay, although it would be a good idea to have the apps engineer for these parts give it a review as well.

[ericserban22]

Hello @thorenscientific, thanks for the review. Regarding the missing zip archives, we are not supposed to port them to GitHub anymore. Other than this I hope I addressed all your suggested changes (and also the ones from the LLM review). If not, let me know and I will make another commit.

[StancaPop]

Looks good to me.

[thorenscientific]

Hi @ericserban22 , sorry for the delay in replying. Gotcha on the zip archives and not porting to GitHub, completely understood. But if we're not providing the files at all, then I'd just get rid of those two pages - why document something that the customer can't get their hands on? That's a "phone call generator" (or nowadays, EngineerZone thread generator)

But if we really do want to keep them, then I believe they could be uploaded to swdownloads?

But another argument for just getting rid of those, looks like there's already no-OS support:
https://github.com/analogdevicesinc/no-OS/tree/main/drivers/adc/ad717x

I don't see an example project but one could be created.

[StancaPop]

Hi @ericserban22 and @thorenscientific, I think it might be better to remove the legacy documentation pages from this PR. Keeping them could create confusion and lead to support questions that we’re no longer able to address.

[thorenscientific]

@StancaPop agreed - if a question ever does come in, better to answer with a new example project in no-OS, vs. having to do archaeology on those old zips.

[StancaPop]

Looks good to me.