nwb-extensions / ndx-template

A template for creating Neurodata Extensions for the NWB neurophysiology data standard
https://nwb.org/
Other
5 stars 8 forks source link

Cross-reference docs to other extensions #1

Open rly opened 5 years ago

rly commented 5 years ago

Currently, intersphinx is used to create cross-references to other documentation, e.g. the core schema. However, this reference to the core is hard-coded in docs/source/conf.py:

intersphinx_mapping = {'core': ('https://nwb-schema.readthedocs.io/en/latest/', None)}

Change this behavior to allow cross-reference to docs of other extensions if the current extension uses other extensions.

Namespace YAML files will have to include an (optional) URL to the documentation of the included neurodatatypes:

namespaces:
- author: Ben Dichter
  contact: example@example.com
  doc: ecog extensions
  name: ecog
  schema:
  - namespace: core
  - neurodata_types:
    - NWBDataInterface
    - Subject
  - documentation: https://nwb-schema.readthedocs.io/en/latest/
  - source: ecog.extensions.yaml
  version: 1.2.1

This will also require a change to NWBNamespaceBuilder in PyNWB and NamespaceBuilder in HDMF:

ns_builder.add_spec(ext_path, neurodata_type, doc_url)

Useful refs: https://stackoverflow.com/questions/30939867/how-to-properly-write-cross-references-to-external-documentation-with-intersphin

jcfr commented 5 years ago

Since after integrating #8 , conf.py will be generated using nwb_docutils.init_sphinx_extension_doc, I suggest to implement this in the associated cli.

See https://github.com/NeurodataWithoutBorders/nwb-docutils/blob/4c555353e9ec0f47af6bbc185a9a5492d1114344/nwb_docutils/init_sphinx_extension_doc.py#L357-L358