[ENH] Link to filename element definitions in filename templates

[tsalo]

Closes None, but will help with #612.

Changes proposed:

• Filename elements (e.g., suffixes, entities, extensions, datatypes) in the filename templates throughout the specification now link to the definitions of those elements. For example, if a filename allows the task entity, that portion of the filename template will link to the task entity definition in the Entities appendix page.

This feels really close. The problem is that the paths aren't working properly.

Basically, hrefs like SPEC_ROOT/99-appendices/09-entities.md#subject are resolving to https://bids-specification--1228.org.readthedocs.build/en/1228/04-modality-specific-files/99-appendices/09-entities.md#subject. Note the 04-modality-specific-files.

[Remi-Gau]

OMG. This looks amazing already.

Definitely worth trying to make this last bit work I think (no pressure)

[Remi-Gau]

Technically we could also link to the suffixes, right?

[tsalo]

Yes, ultimately I'd like to link to the (1) entities, (2) datatypes, (3) entity value formats (index vs. label vs. enum), (4) suffixes, and (5) extensions. Adding in new links won't be too hard, so once I actually have the links working I'll add a whole bunch of other ones.

[tsalo]

It seems to be working, and it is GLORIOUS!!

[sappelhoff]

amazing 👏 🚀

[tsalo]

Oh but now the PDF looks awful. 😞

[sappelhoff]

can you selectively switch this behavior off for the pdf build?

[tsalo]

@sappelhoff I have refactored things a bit to toggle the formatting based on a new function argument (pdf_format). I need to figure out how to get the pdf build to use this new argument now.

[Remi-Gau]

Great work @tsalo

[sappelhoff]

Thanks @tsalo!

[tsalo]

Uh oh, it looks like the new links don't point to the specific language and version. They were fine in the CI build, but I guess that this specific issue wasn't covered.

So instead of:

https://bids-specification.readthedocs.io/en/latest/99-appendices/09-entities.html#sub

Links go to:

https://bids-specification.readthedocs.io/99-appendices/09-entities.html#sub

[tsalo]

This seems to be the relevant part of the mkdocs documentation: https://www.mkdocs.org/user-guide/writing-your-docs/#linking-from-raw-html. Unfortunately, I still don't know how to "manually format the link appropriately".

[effigies]

We can't. We'll need to figure out the SPEC_ROOT stuff.

[tsalo]

I think I have SPEC_ROOT rendering correctly. I assumed that the problem was more complicated than it seems to be.