Be stricter when building documentation

[hoechenberger]

Helps with #978

Before merging …

• [ ] Changelog has been updated (docs/source/changes.md)

[hoechenberger]

@larsoner I think it's working

Generating config docs …
Parsing /home/circleci/project/mne_bids_pipeline/_config.py to generate settings .md files.
100% 2350/2350 [00:00<00:00, 537643.29it/s]
Building the documentation …
INFO    -  [macros] - Macros arguments: {'module_name': 'main', 'modules': [], 'render_by_default': True, 'include_dir': '', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep', 'on_error_fail': False, 'verbose': False}
INFO    -  [macros] - Extra variables (config file): ['social', 'version']
INFO    -  [macros] - Extra filters (module): ['pretty']
INFO    -  DeprecationWarning: The `get_logger` function is deprecated.
  File "/home/circleci/.pyenv/versions/3.12.4/lib/python3.12/site-packages/_griffe/agents/nodes/runtime.py", line 17, in <module>
    _logger = get_logger("griffe.agents.nodes._runtime")
  File "/home/circleci/.pyenv/versions/3.12.4/lib/python3.12/site-packages/_griffe/logger.py", line 117, in get_logger
    warnings.warn("The `get_logger` function is deprecated.", DeprecationWarning, stacklevel=1)

INFO    -  DeprecationWarning: The `name` parameter is deprecated.
  File "/home/circleci/.pyenv/versions/3.12.4/lib/python3.12/site-packages/_griffe/docstrings/google.py", line 49, in <module>
    _warn = docstring_warning("griffe.docstrings.google")
  File "/home/circleci/.pyenv/versions/3.12.4/lib/python3.12/site-packages/_griffe/docstrings/utils.py", line 83, in docstring_warning
    warnings.warn("The `name` parameter is deprecated.", DeprecationWarning, stacklevel=1)

Generating option->step mapping: 100% 56/56 [00:00<00:00, 259.29it/s]
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/circleci/project/docs/site
WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - governance.md
INFO    -  Updated copyright to Copyright &copy; MNE-BIDS-Pipeline authors, last updated 2024/07/31
WARNING -  Doc file 'getting_started/freesurfer.md' contains a link 'basic_usage.md#adjust-your-configuration-file', but the doc 'getting_started/basic_usage.md' does not contain an anchor '#adjust-your-configuration-file'.

Aborted with 2 warnings in strict mode!
make: *** [Makefile:22: doc] Error 1

Exited with code exit status 2

[larsoner]

Nice that it caught that! But if I locally put in the same sort of error we saw in #977:

diff --git a/docs/source/v1.9.md.inc b/docs/source/v1.9.md.inc
index 5c550af..e82bfd1 100644
--- a/docs/source/v1.9.md.inc
+++ b/docs/source/v1.9.md.inc
@@ -6,7 +6,7 @@
 - The type annotations in the default configuration file are now easier to read: We
   replaced `Union[X, Y]` with `X | Y` and `Optional[X]` with `X | None`. (#908, #911 by @hoechenberger)
 - Epochs metadata creation now supports variable time windows by specifying the names of events via
-  [`epochs_metadata_tmin`][mne_bids_pipeline._config.epochs_metadata_tmin] and
+  [`epochs_metadata_tmin`][mne_bids_pipeline._config. epochs_metadata_tmin] and

and rebuild docs I don't get an error related to that unfortunately and the error persists:

I think this is already good progress so I'll fix the linking problem, set omitted_files: info (we intentionally omit governance.md I think?) and merge after removing the "fixes" tag.

[larsoner]

... just noticed this is draft mode so I'll leave it open in case you want to do more @hoechenberger, in the meantime I pushed a commit. Feel free to revert or force-push over if you want

[hoechenberger]

@larsoner No feel free to take over and add more changes if you want, i'll be busy for the rest of the day (week?)

please do add a small changelog entry though if you can

merci !

[hoechenberger]

we intentionally omit governance.md I think?

yes maybe we can make a per-file exclude

---

i'm surprised the broken link from your example is not recognized 🤔