Schema documentation does not reflect the latest version

[stephprince]

The schema format overview documentation page does not reflect the stable/latest versions of the schema, it is displaying version 2.7.0 instead of 2.8.0/2.9.0-alpha.

The readthedocs builds have succeeded, but output from the logs suggests that the latest namespace version is ignored because namespace version 2.7.0 is already loaded. It's not clear to me why this would be the case.

python -m sphinx -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html
Running Sphinx v8.1.3
/home/docs/checkouts/readthedocs.org/user_builds/nwb-schema/checkouts/latest/docs/format/source/conf.py:220: SyntaxWarning: invalid escape sequence '\s'
  """
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
loading intersphinx inventory 'hdmf-common-schema' from https://hdmf-common-schema.readthedocs.io/en/stable/objects.inv ...
/home/docs/checkouts/readthedocs.org/user_builds/nwb-schema/envs/latest/lib/python3.12/site-packages/hdmf/spec/namespace.py:535: UserWarning: Ignoring cached namespace 'core' version 2.9.0-alpha because version 2.7.0 is already loaded.
  warn("Ignoring cached namespace '%s' version %s because version %s is already loaded."

[stephprince]

Ah, I forgot that pynwb 2.8.3 does not yet support nwb-schema 2.8.0. Does this mean that the format overview page will always reflect the latest pynwb-supported version of the schema?

I can close this issue if that is the expected behavior.

[rly]

I don't know if something changed, but the documentation page currently reflects the stable and latest versions of the schema. The "latest" page includes the release notes just merged to main this afternoon, after the latest pynwb release.

The warning persists though:

/home/docs/checkouts/readthedocs.org/user_builds/nwb-schema/envs/latest/lib/python3.12/site-packages/hdmf/spec/namespace.py:590: UserWarning: Ignoring the following cached namespace(s) because another version is already loaded:
--
  | core - cached version: 2.10.0-alpha, loaded version: 2.9.0
  | Please update to the latest package versions.
  | self.warn_for_ignored_namespaces(ignored_namespaces)

[rly]

Ah, the release notes are updated, but the new type map is still ignored because the core namespace from PyNWB takes precedence. Yes, that's a bug. I think that can be fixed by not setting spec_default_type_map in https://github.com/NeurodataWithoutBorders/nwb-schema/blob/1cbd9a8c11dd872e1fbecccb0273f2812704d11e/docs/format/source/conf_doc_autogen.py#L86C1-L86C22

[rly]

Attempting fix in #663