To me, one of the best arguments to move to Sphinx was so that manual pages
could have links directly into locations in the Users manual. Not possible in
practice with a .pdf users manual.
With the manual in .rst and manual pages generated into .md this still appear
to be impossible.
1) when Sphinx is processing .md pages it appears to not know about labels
defined in .rst files so [matrix layout](sec_mat_something) doesn't work
2) Raw, cruder things like [matrix
layout](../../manual/mat.html#matrix-and-vector-layouts-and-storage-locations)
don't work because it doesn't realize what is inside is a raw URL. I am
guessing it needs the http:// at the beginning to realize it is a HTPP url and
not a markdown thing.
3) [matrix
layout](https://petsc.org/main/docs/manual/mat/#matrix-and-vector-layouts-and-storage-locations)
works
but hardwiring it this way is horrible. Could be release, could be (would be
most of the time) a strange URL when running inside the CI. Is there a way to
start with https::// but be a relative link?
figuring the anchor that Sphinx creates from a label
(#matrix-and-vector-layouts-and-storage-locations) is super cumbersome.
Is the only good solution to somehow generate .rst files with sowing? How
come that wasn't done initially and instead .md files were generated? It seems
insanely bad to have this mixture of .md and .rst for a website.
This is frustrating, to be sold on a technology (Sphinx) for a particular
goal when that technology cannot even satisfy that goal. (Yes the web pages
look much nicer, but aside from the search, the functionality of the website is
no better than before!).
Barry
