doc: Sphinx config nitpicky #2494
Conversation
| ('py:mod', 'artiq.experiment'), | ||
| ('py:class', 'dac34H84'), | ||
| ('py:class', 'trf372017'), |
There was a problem hiding this comment.
Why are those three ignored?
There was a problem hiding this comment.
There's three options with anything currently 'linked' to that isn't actually documented in the manual -- either add something to the manual that the link can be routed to (e.g. the empty :automodule: added for artiq.language.units), remove the attempted link (many such cases), or place them in the ignore (under the philosophy that they are real objects and merit the associated formatting signifiers, they're simply undocumented in the manual and there's no intention to change this.)
These three seemed to fit the last category to me but either of the other two tactics could be used if we prefer. The DAC and TRF classes in particular could also just be added to the core driver reference, there's not much in them that's documented but it'd make the links work and the source accessible through Sphinx
ARTIQ Pull Request
Description of Changes
Turn on Sphinx's 'nitpicky' setting, which brings up a warning for every reference link which Sphinx can't actually connect to anything, which provides feedback to avoid the kind of link rot #2493 spends a lot of time patching and which has previously been pretty annoying to track. This branch on its own still brings up unresolved warnings but when combined with the commits in #2493 should build warning-free.
Related Issue
Type of Changes
Steps (Choose relevant, delete irrelevant before submitting)
All Pull Requests
Documentation Changes
cd doc/manual/; make html) to ensure no errors.Git Logistics
git rebase --interactive). Merge/squash/fixup commits that just fix or amend previous commits. Remove unintended changes & cleanup. See tutorial.Licensing
See copyright & licensing for more info.
ARTIQ files that do not contain a license header are copyrighted by M-Labs Limited and are licensed under LGPLv3+.