Skip to content

Fix documentation/image links #4025

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 30, 2024
Merged

Fix documentation/image links #4025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2cebcdd
Fix documentation/image links
jhrcek Jan 29, 2024
dd23a00
Fix sphinx warnings
jhrcek Jan 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/contributing/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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..?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will it cause a version mismatch though🤔

Copy link
Collaborator Author

@jhrcek jhrcek Jan 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's think through the implications of this change:

  1. 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 for bench/README on 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:
Screenshot from 2024-01-30 05-34-52

  1. With this PR: the link is renered correctly and points to readme on master:
    Screenshot from 2024-01-30 05-40-02

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 😄

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### Tracing

Expand All @@ -233,7 +233,7 @@ Adding support for new editors is fairly easy if the editor already has good sup
In that case, there will likely be an editor-specific support system for this (like `lsp-mode` for Emacs).
This will typically provide instructions for how to support new languages.

In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](#configuring-haskell-language-server) and
In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](../configuration.md#configuring-haskell-language-server) and
for them to configure how the server is started.

## Building the docs
Expand Down
1 change: 0 additions & 1 deletion docs/contributing/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,3 @@ Contributing

contributing
plugin-tutorial
releases
10 changes: 5 additions & 5 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Provided by: `hls-call-hierarchy-plugin`

Shows ingoing and outgoing calls for a function.

![Call Hierarchy in VSCode](https://github.com/haskell/haskell-language-server/raw/2857eeece0398e1cd4b2ffb6069b05c4d2308b39/plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)
![Call Hierarchy in VSCode](../plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)

## Highlight references

Expand Down Expand Up @@ -199,7 +199,7 @@ Rewrites imported names to be qualified.

![Qualify Imported Names Demo](../plugins/hls-qualify-imported-names-plugin/qualify-imported-names-demo.gif)

For usage see the ![readme](../plugins/hls-qualify-imported-names-plugin/README.md).
For usage see the [readme](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-qualify-imported-names-plugin/README.md).

### Add missing class methods

Expand Down Expand Up @@ -264,7 +264,7 @@ Known Limitations:

![Change Type Signature Demo](../plugins/hls-change-type-signature-plugin/change2.gif)

![Link to Docs](../plugins/hls-change-type-signature-plugin/README.md)
[Link to Docs](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-change-type-signature-plugin/README.md)

### Add argument to function

Expand All @@ -284,7 +284,7 @@ Convert a datatype to GADT syntax.

![GADT Demo](../plugins/hls-gadt-plugin/gadt.gif)

![Link to Docs](../plugins/hls-gadt-plugin/README.md)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Screenshot from 2024-01-29 19-42-43

[Link to Docs](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-gadt-plugin/README.md)

### Expand record wildcard

Expand Down Expand Up @@ -318,7 +318,7 @@ Provided by: `hls-eval-plugin`

Evaluates code blocks in comments with a click. [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md).

![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
![Eval Demo](../plugins/hls-eval-plugin/demo.gif)

Known limitations:

Expand Down