Skip to content
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

Jump to bottom

Do not use path cross-references #296

Closed
lucyleeow opened this issue Dec 6, 2023 · 5 comments
Closed

Do not use path cross-references #296

lucyleeow opened this issue Dec 6, 2023 · 5 comments
Labels
task

Comments

@lucyleeow
Copy link
Collaborator

🧰 Task

We have cross references using paths (relative and absolute) to files, e.g.,:

docs/docs/community/index.md

Line 13 in 0c7029e

[contributing guide](../developers/index).

This breaks if we re-organise our directory structure. Could we use explicit targets instead?

This would make it easier if we re-organise our docs (e.g., #282) or make changes as we update our API etc.
@lucyleeow lucyleeow added the task label Dec 6, 2023
@lucyleeow lucyleeow changed the title Do not use path cross-links Do not use path cross-references Dec 6, 2023
@lucyleeow
Copy link
Collaborator Author

lucyleeow commented Dec 6, 2023 •
edited
Loading

cc @melissawm WDYT ?

@psobolewskiPhD
Copy link
Member

I'm in favor, we've run into this before. Not sure there's a good way to mass implement this. First need to add targets to everything (e.g. that dev/index doesn't have one) and then fix the links. And then add an explanation to the docs contribution guide.

@melissawm
Copy link
Member

Sounds good to me!

@lucyleeow
Copy link
Collaborator Author

Yeah I am not sure there is a way to automate this. Let me have a go at doing it by hand 😬

@lucyleeow lucyleeow mentioned this issue Dec 7, 2023
Merged
psobolewskiPhD pushed a commit that referenced this issue Jan 23, 2024
@lucyleeow
Use reference labels instead of paths (#301)
e9e874f 
# References and relevant issues
towards #296

# Description
 Uses references labels instead of paths. A few notes:

* I have left all the paths inside
`docs/plugins/virtual_environment_docs` as they just reference files
within that folder so I think we're safe
* I did not know how to deal with `gallery/` links. Does sphinx-tag
automatically generate the gallery index/readme page..?
* Standardised use of `-` between words in reference labels
* Removed `napari` from some reference labels, as there is no 'plugin'
equivalent thus its obvs it is about napari
* Images! - We still have a lot of relative paths to image/animation
files. These would ideally be absolute paths, meaning they would be fine
as long as the images stay in the same folder, but I could not be
bothered. Maybe will leave this to be fixed when needed....
@lucyleeow
Copy link
Collaborator Author

I think this can be closed now, I've done most of it and the remaining I don't think needs to be done. Thanks all!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
task
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@melissawm @lucyleeow @psobolewskiPhD