fix: Add or correct URL fragments in internal links (#2241)

* fix: Autogenerate correct link anchors

* fix: Update hand-written links

* fix: Add default anchor for sense 1

* chore: Exclude README and pregh-changes.md from being rendered

Author: effigies

mkdocs.yml

@@ -51,6 +51,9 @@ nav:
       - Website: https://bids-standard.github.io/bids-starter-kit/
       - Tutorials: https://bids-standard.github.io/bids-starter-kit/tutorials/tutorials.html
       - GitHub repository: https://github.com/bids-standard/bids-starter-kit
+exclude_docs: |
+  README.md
+  pregh-changes.md
 theme:
   name: material
   favicon: images/favicon.png

src/common-principles.md

@@ -591,7 +591,7 @@ Example:
 ```
 
 Each level can be described with a string as in the example above,
-or with an object containing the fields [`Description`](./glossary.md#description-metadata)
+or with an object containing the fields [`Description`](./glossary.md#description-sense-1-metadata)
 and [`TermURL`](./glossary.md#termurl-metadata)
 like in the example below.
 
@@ -1159,8 +1159,8 @@ to suppress warnings or provide interpretations of your filenames.
 
 <!-- Link Definitions -->
 
-[dataset-description]: modality-agnostic-files/data-summary-files.md
-[dataset_description.json]: modality-agnostic-files/data-summary-files.md#dataset_descriptionjson
-[derived-dataset-description]: modality-agnostic-files/data-summary-files.md#derived-dataset-and-pipeline-description
+[dataset-description]: modality-agnostic-files/dataset-description.md
+[dataset_description.json]: modality-agnostic-files/dataset-description.md#dataset_descriptionjson
+[derived-dataset-description]: modality-agnostic-files/dataset-description.md#derived-dataset-and-pipeline-description
 [deprecated]: #definitions
 [uris]: #uniform-resource-indicator

src/modality-specific-files/positron-emission-tomography.md

@@ -314,7 +314,7 @@ Knudsen et al. 2020
 recommends recording participant body weight.
 If recorded once per participant, these data SHOULD be included in the
 [Participants file](../modality-agnostic-files/data-summary-files.md#participants-file) or as
-[Phenotypic and assessment data](../modality-agnostic-files/data-summary-files.md#phenotypic-and-assessment-data).
+[Phenotypic and assessment data](../modality-agnostic-files/phenotypic-and-assessment-data.md#phenotypic-and-assessment-data).
 
 For example:
 

tools/schemacode/src/bidsschematools/render/tables.py

@@ -73,7 +73,8 @@ def _make_object_table(
         # except for subobjects (if table_type) and
         # "additional columns" (field_name.startswith("**"))
         if table_type and not field_name.startswith("**"):
-            field_name = f"[{field_name}]({GLOSSARY_PATH}.md#objects.{table_type}.{element})"
+            sub = table_type if table_type != "subobject" else "metadata"
+            field_name = f"[{field_name}]({GLOSSARY_PATH}.md#objects.{sub}.{element})"
 
         # Grab any requirement level information and text to be added to the description string
         requirement_info, description_addendum = field_info[element]["table_info"]
@@ -297,6 +298,10 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
     formats = ["Format"]
     table = [formats]
 
+    suffix_map = {
+        obj.value: key for key, obj in schema.objects.suffixes.items()
+    }
+
     # Compose header and formats first
     for long_name in schema.rules.entities:
         entity = schema.objects.entities[long_name]
@@ -320,7 +325,7 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
 
     for (dtype, entities), suffixes in rows.items():
         suf_str = " ".join(
-            f"[{suffix}]({GLOSSARY_PATH}.md#objects.suffixes.{suffix})" for suffix in suffixes
+            f"[{suffix}]({GLOSSARY_PATH}.md#objects.suffixes.{suffix_map[suffix]})" for suffix in suffixes
         )
         # TODO: <br> is specific for html form
         fmt_str = f"[{dtype}]({GLOSSARY_PATH}.md#objects.datatypes.{dtype})<br>({suf_str})"

tools/schemacode/src/bidsschematools/render/text.py

@@ -152,6 +152,8 @@ def make_glossary(schema, src_path=None):
         if obj_desc is None:
             raise ValueError(f"{obj_marker} has no description.")
 
+        if "sense 1" in obj_key:
+            text += f'\n<a name="{obj_marker.split("__", 1)[0]}"></a>'
         text += f'\n<a name="{obj_marker}"></a>'
         text += f"\n## {obj_key}\n\n"
         text += f"**Name**: {obj_def['display_name']}\n\n"