[INFRA] Move entity definitions to a separate page

[tsalo]

Closes #567.

Changes proposed:

1. Add a new appendix for entity definitions, using bids_schema.py.
2. Link to appendix entity definitions in the entity table, using bids_schema.py.
3. Remove section headers for entity definitions in main text, to ensure that the search bar will point to the entities appendix page.
4. Add links from main text to appendix definitions.
5. Add a new function and command line subparser to bids_schema.py to generate the new appendix page.

Notes:

• I didn't include Derivatives in this, but that might be something to do in the future. It will involve (1) adding derivatives-specific entities to the appendix (or a separate appendix), (2) supporting derivatives in the schema, and (3) adding links to the appendix in the Derivatives sections of the text.
• The specification text is largely unchanged, but we will want to start removing entity definitions in the text, while leaving anything that provides necessary context for different modalities, such as examples.

[tsalo]

It doesn't look like internal links work in the PDF, so we may need a workaround for that (even once we have the schema).

EDIT: Per maintainers call, this can be considered a web-only feature. It's not a big deal if the PDF cannot support these links, even though it should be possible with some work.

[tsalo]

@sappelhoff I switched to just linking from the text to the new page and dropping the section headers in the text. What do you think of the new structure?

Ultimately I'd like to minimize that "glue" (i.e., the section-specific entity descriptions) while maintaining readability and useful section-specific information (like examples), but I think this is a good start.

[sappelhoff]

nice, this looks like a less invasive start to me, which we can iterate upon in the future.

dropping the section headers in the text

why did you drop those?

[tsalo]

I dropped the section headers for two reasons. First, the section headers only appeared for the first definition of each entity, setting that first definition up as the canonical one. If every data type section had subsections (with headers) for all of its applicable entities, I would have left it. Now, however, the main definition for each entity is in the Entities page, and each entity-specific text throughout the rest of the specification should slowly be downsized to just reflect additional information for that data type specifically. The second reason is that the section headers in the Entities page should be the ones that show up in the search bar.

[sappelhoff]

I think the proposed changes are a valuable change to the specification. Thanks for preparing it @tsalo - please tag some more people you'd like to review this (or write them an email, as some may not check their notifications)

[tsalo]

Thanks @sappelhoff! Pinging @yarikoptic and @effigies.

[yarikoptic]

This is just wonderful, thank you @tsalo !

One little comment: I would have added a comment (probably just HTMLs') on top of entities and entities table markdown files:

<!-- 
  This file is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY. 
  Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#updating-the-schema 
-->

[yarikoptic]

EDIT: Per maintainers call, this can be considered a web-only feature. It's not a big deal if the PDF cannot support these links, even though it should be possible with some work.

IMHO worth an issue (if not there already) so someone eager could just make it resolved! Would be a great addition to PDF rendering.

[tsalo]

One little comment: I would have added a comment (probably just HTMLs') on top of entities and entities table markdown files:

<!-- 
  This file is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY. 
  Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#updating-the-schema 
-->

That is a great idea! I'll add this to the entities and entity table pages. I'm just putting it in the intro text for now, but it could be built into its own function at some point.

I'll open an issue about the internal linking.

[tsalo]

Thanks @sappelhoff and @yarikoptic. I'll wait the five days (starting yesterday), in case anyone wants to raise any concerns, before merging.

@yarikoptic Absolutely, the text could be moved out into a separate function, although I want to hold off on actually implementing that because I think the current code is going to be substantially restructured in the not-too-distant future.

[tsalo]

The five day embargo period is over with no concerns raised, so I'm merging now. Thank you @sappelhoff and @yarikoptic!