Spatial category in included.md - needs review about scores

[nicholasloveday]

Looks good to me!

[nikeethr]

Btw the FSS stuff looks fine to me otherwise. The above suggestion is probably for a different issue.

[Steph-Chong]

Notes:

• The tutorial links will 404. (When this happens, I change "latest" to "develop" to check the link will work when merged to main)
• The API links will incorrectly resolve to the top of the API documentation page. (Again, I change "latest" to "develop", and then check it resolves to the correct section of the API documentation)

[nikeethr]

strange... not sure why develop references api from "latest"...

[Steph-Chong]

strange... not sure why develop references api from "latest"...

Tennessee and I have adopted this strategy deliberately. We can't use relative paths, as the relative paths don't work across GitHub, PyPI and readthedocs.

Tennessee is planning to do another merge to main fairly soon, so the links will work after that.

The alternative (which we did try previously), is to first includes link to develop, then manually search for and manually update every develop link before each merge to main. While we started off doing that, we changed to the current strategy.

[Steph-Chong]

If either of you are aware of a better strategy for the links, please feel free to share. Tennessee and I know the current approach isn't ideal, it was just the best we could come up with!

[nikeethr]

This should in theory work: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#inline-links-with-implicit-text

I'll just quickly test it out

[Steph-Chong]

An additional note (which I didn't include before): within the same page, relative paths work fine.

For instance, in the Contributing Guide (https://scores.readthedocs.io/en/develop/contributing.html), I have can included things such as "Please follow the workflow for submitting pull requests outlined above." - and the #workflow-for-submitting-pull-requests will take me to that section on that page.

My understanding is one of the biggest issue was links in the README.md not resolving in PyPI - I think in the early days (when I wasn't involved), this caused a fair few problems. So I think that was Tennessee's initial motivation to use full URLs.

Tennessee also said there were issues with links behaving differently in GitHub versus readthedocs.

[nikeethr]

Ok so here are examples that worked for me:

[API](project:./api.md#scores.continuous.additive_bias)
[Tutorial](project:./tutorials/Flip_Flop_Index.md)

The main difference is the project: prefix and instead of .html targetting .md. That should allow you to strip out the absolute parts hopefully, again hard to tell without actually pushing it and building it with readthedocs.

As you say they may not work on md files that are shared between what's in github and readthedocs. Although I think any links in github README.md should probably just point to "latest" or github itself.

I think its mainly nice to have the API/tutorials in sync with the appropriate branch.

[tennlee]

Thanks for coming up with that approach Nikeeth. In the past, there were so many issues, I think it will involve some time to really test any new way of doing things, so I'm going to hold that off until after version 1.0 when we can take some time over it. I'll make a note and keep it on a list of things to look into in future.