Skip to content

docs: fix a bunch of things#383

Open
jsstevenson wants to merge 32 commits intov1from
fix-docs
Open

docs: fix a bunch of things#383
jsstevenson wants to merge 32 commits intov1from
fix-docs

Conversation

@jsstevenson
Copy link
Contributor

@jsstevenson jsstevenson commented Dec 27, 2025

close #367

As noted here, there are a lot of warnings when you attempt to build the docs:

render1767110113251-ezgif com-resize(1)

Many of these are inconsequential, but a lot of them are dead links, deprecated files, incomplete/WIP files, etc that are hanging out and polluting search results or causing confusion. And with so many warnings, it's hard to know when a change introduces a new problem.

This PR handles almost all of them (a couple require upstream fixes that I have separately produced PRs for). I have tried to be very careful about altering or removing anything beyond my own understanding, and have kept a running list of changes made:

  • The embedding of the maturity model page was messed up -- it was like a hybrid symlink/RST file. Changed this to just be an RST file with an .. include.
  • Exclude pages in def/ from the toctree, so they only show up in search results if they're purposely embedded in a page
  • Remove some orphaned pages, where I was confident that they were intended for removal (or at least, I figured trying to delete them might nudge someone to figure out the correct solution):
    • Remove docs/source/x-figure-formatting-test.rst, docs/source/x-community-profiles/acmg-2015.rst, and docs/source/x-community-profile-sets/index.rst. The latter gave me pause, and initially, per recommendation from Larry on a PR of Kori's a few weeks ago, I jammed a link to it from a different page. But it contains a bunch of additional broken links and seems to use some old names for things, so I went ahead and just removed it on the theory that it wasn't intended to be saved.
    • Remove this orphaned section on "domain entities" that mostly repeated what's given here. The latter was last edited after the former and I think it's more consistent with the rest of the docs to provide it on a flat page. It doesn't have the pretty figure, though, nor does it provide separate sections for Drug or Phenotype.
    • Remove docs/source/faq.rst, its content had been copied out to specific appendices
    • Remove docs/source/overview.rst, its content was largely duplicated elsewhere and it was full of a lot of unfinished sentences or placeholder content, see eg https://va-spec.ga4gh.org/en/1.0/overview.html#va-spec-implementation-of-the-sepio-framework
    • Remove modeling-foundations.rst, it had a bunch of dead links and appeared to have been restructured into a subdirectory of pages
    • Remove profiling-methodology.rst. It duplicated a target for another page that IS included in a toctree, and included a bunch of broken refs. Was generally duplicated by other, included pages.
  • Remove some blank, orphaned pages.
  • Fix some :ref: typos and add some missing targets. Generally fixed a lot of RST formatting errors.
  • The generated def pages include :ref:s out to VRS/GKS Core/Cat-VRS classes like Allele etc. These, of course, do not work unless you build corresponding pages here. I copied what Cat-VRS does and created an "imported models" appendix to hold simple pages for these models.
  • I removed the sentence "This transparency will be important as the minimal Profiles included in VA-Spec 1.0 expand in different ways, as described in the Future Directions appendix." from the very end of the Introduction page. No such "Future Directions" appendix page exists, as far as I can tell.
  • Fixed some dead links. You can use make linkcheck to automatically test all links, but this seems to yield a lot of false positives. Nevertheless, I did find a few. I added use of linkext in a few pages, which is a more ergonomic way of doing this "dynamic rst epilog" thing for github links -- would be nice to move the rest over at some point

Once all build warnings are resolved, I'd like to introduce a check in GitHub Actions to flag when new ones are introduced, so that PR authors and reviewers get more clarity about possible future problems.

@jsstevenson jsstevenson changed the title symlink -> include docs: fix a bunch of things Dec 27, 2025
@jsstevenson jsstevenson marked this pull request as ready for review January 3, 2026 03:00
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.

RTD invalid ref targets

1 participant