Fix documentation/image links #4025
Conversation
| @@ -284,7 +284,7 @@ Convert a datatype to GADT syntax. | |||
|
|
|||
|  | |||
|
|
|||
|  | |||
There was a problem hiding this comment.
These are not images (which is what ! syntax in markdown represent) but just plain links.
I'm trying to unbreak "broken link" appearance in places like this
| @@ -221,7 +221,7 @@ Run the benchmarks with `cabal bench`. | |||
|
|
|||
| It should take around 25 minutes and the results will be stored in the `bench-results` folder. To interpret the results, see the comments in the `bench/Main.hs` module. | |||
|
|
|||
| More details in [bench/README](../../bench/README.md) | |||
| More details in [bench/README](https://github.com/haskell/haskell-language-server/blob/master/bench/README.md) | |||
There was a problem hiding this comment.
These links are referring to stuff outside of docs directory, so sphinx is unable to create proper links.
Rather than trying to change sphinx configuration, i think it's simpler to just link to relevant docs on master branch..?
There was a problem hiding this comment.
will it cause a version mismatch though🤔
There was a problem hiding this comment.
Let's think through the implications of this change:
- Before this PR, the links (not images, which are copied during the build!) that point to relative file paths outside of docs directory are not rendered as links:
Example: search forbench/READMEon this page.
When building the docs by running make html in the docs folder I get get the following warning:
/home/jhrcek/Devel/github.com/haskell/haskell-language-server/docs/contributing/contributing.md:224: WARNING: Unknown source document '/home/jhrcek/Devel/github.com/haskell/haskell-language-server/bench/README' [myst.xref_missing]
And the resulting html has no links:
- With this PR: the link is renered correctly and points to readme on master:
You're right that this is not ideal, because the readme on master can be modified in a way that makes is "incompatible" with the rendered version of the docs or it can be even removed etc. But this is what most of the other links on the page are currently doing (just pointing to master version of the doc on github).
3)The ideal solution would be to replace "master" within those links with "the commit hash of the commit from which the docs were built" which would tie the rendered docs to the state of the repo when they were built. Unfortunately I don't know what's the "canonical" way to do this with sphinx (I can only think of hacks like adding a placeholder in all those links and running sed -i /PLACEHOLDER/$(git-rev parse HEAD)/g before building with shinx, which feels like hack). I'm open to suggestions how to implement such a thing correctly 😄
There was a problem hiding this comment.
I think for things that have a relatively stable location what you're doing here is okay. In particular, I could imagine replacing this link with the prose "the readme for the benchmarks", which would direct people to the same place. If anything, I'd be tempted to just use the prose.
I built the docs locally and fixed most sphinx warnings.