Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
close #367
As noted here, there are a lot of warnings when you attempt to build the docs:
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:
.. include.def/from the toctree, so they only show up in search results if they're purposely embedded in a pagedocs/source/x-figure-formatting-test.rst,docs/source/x-community-profiles/acmg-2015.rst, anddocs/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.docs/source/faq.rst, its content had been copied out to specific appendicesdocs/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-frameworkmodeling-foundations.rst, it had a bunch of dead links and appeared to have been restructured into a subdirectory of pagesprofiling-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.:ref:typos and add some missing targets. Generally fixed a lot of RST formatting errors.defpages include:ref:s out to VRS/GKS Core/Cat-VRS classes likeAlleleetc. 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.make linkcheckto 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 pointOnce 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.
:ref:s are actually HTTP hyperlinks, which Sphinx can't check the validity of.