Fix build warnings/errors in docs (NeurodataWithoutBorders#1462)

* Fix bad :py:method roles in ecephys tutorial * Fix bad heading underlines in file tutorial * Remove old overview_nwbfile.rst file to avoid build errors due to duplicate anchors * Replace hard-coded links in software process with external links to avoid build warnings * Use external links instead of hard coded links in update_requirements.rst * Update relative links in software process to shorten display text * Add module docstring for validation tool * Update software_process.rst Co-authored-by: Ryan Ly <[email protected]>
h-mayorquin · Apr 22, 2022 · 79183f2 · 79183f2
1 parent a11cc3f
commit 79183f2
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 131 deletions.
diff --git a/docs/gallery/domain/ecephys.py b/docs/gallery/domain/ecephys.py
@@ -125,7 +125,7 @@
 nwbfile.electrodes.to_dataframe()
 
 #######################
-# .. note:: When we added an electrode with the :py:method:`~pynwb.file.NWBFile.add_electrode`
+# .. note:: When we added an electrode with the :py:meth:`~pynwb.file.NWBFile.add_electrode`
 #    method, we passed in the :py:class:`~pynwb.ecephys.ElectrodeGroup` object for the ``"group"`` argument.
 #    This creates a reference from the ``"electrodes"`` table to the individual :py:class:`~pynwb.ecephys.ElectrodeGroup`
 #    objects, one per row (electrode).
@@ -141,7 +141,7 @@
 # To create the :py:class:`~pynwb.ecephys.ElectricalSeries` objects, we need to reference a set of rows
 # in the ``"electrodes"`` table to indicate which electrodes were recorded.
 # We will do this by creating a :py:class:`~pynwb.core.DynamicTableRegion`, which is a type of link that allows you to reference
-# :py:method:~pynwb.file.NWBFile.create_electrode_table_region` is a convenience function that creates a :py:class:`~pynwb.core.DynamicTableRegion` which references the ``"electrodes"`` table.
+# :py:meth:~pynwb.file.NWBFile.create_electrode_table_region` is a convenience function that creates a :py:class:`~pynwb.core.DynamicTableRegion` which references the ``"electrodes"`` table.
 #
 
 
@@ -263,7 +263,7 @@
 # Spike times are stored in the :py:class:`~pynwb.misc.Units` table, which is a subclass of :py:class:`~hdmf.common.table.DynamicTable`.
 # Adding columns to the :py:class:`~pynwb.misc.Units` table is analogous to how we can add columns to the ``"electrodes"`` and ``"trials"`` tables.
 #
-# We will generate some random spike data and populate the :py:method:`~pynwb.misc.Units` table using the :py:class:`~pynwb.file.NWBFile.add_unit`
+# We will generate some random spike data and populate the :py:meth:`~pynwb.misc.Units` table using the :py:class:`~pynwb.file.NWBFile.add_unit`
 # method. Then we can display the :py:class:`~pynwb.misc.Units` table as a pandas :py:class:`~pandas.DataFrame`.
 
 nwbfile.add_unit_column(name='quality', description='sorting quality')

diff --git a/docs/gallery/general/file.py b/docs/gallery/general/file.py
@@ -2,7 +2,7 @@
 .. _basics:
 
 NWB File Basics
-==================
+===============
 
 This example will focus on the basics of working with an :py:class:`~pynwb.file.NWBFile` object,
 including writing and reading of an NWB file, and giving you an introduction to the basic data types.
@@ -171,7 +171,7 @@
 # .. _basic_subject:
 #
 # Subject Information
-# ----------------
+# -------------------
 #
 # In the :py:class:`~pynwb.file.Subject` object we can store information about the experimental subject,
 # such as ``age``, ``species``, ``genotype``, ``sex``, and a ``description``.
@@ -272,7 +272,7 @@
 # .. _basic_spatialseries:
 #
 # Spatial Series and Position
-# ----------------
+# ---------------------------
 #
 # :py:class:`~pynwb.behavior.SpatialSeries` is a subclass of :py:class:`~pynwb.base.TimeSeries`
 # that represents the spatial position of an animal over time.
@@ -333,7 +333,7 @@
 
 ####################
 # Behavior Processing Module
-# ----------------
+# --------------------------
 #
 # :py:class:`~pynwb.base.ProcessingModule` is a container for data interfaces that are related to a particular
 # processing workflow. NWB differentiates between raw, acquired data (*acquisition*), which should never change,

diff --git a/docs/source/overview_nwbfile.rst b/docs/source/overview_nwbfile.rst
diff --git a/docs/source/software_process.rst b/docs/source/software_process.rst
@@ -45,32 +45,27 @@ Requirement Specifications
 
 There are 5 kinds of requirements specification in PyNWB.
 
-The first one is the requirements-min.txt_ file, which lists the package dependencies and their minimum versions for
+The first one is the :pynwb:`requirements-min.txt <blob/dev/requirements-min.txt>` file, which lists the package dependencies and their minimum versions for
 installing PyNWB.
 
-The second one is requirements.txt_, which lists the pinned (concrete) dependencies to reproduce
+The second one is :pynwb:`requirements.txt <blob/dev/requirements.txt>`, which lists the pinned (concrete) dependencies to reproduce
 an entire development environment to use PyNWB.
 
-The third one is requirements-dev.txt_, which lists the pinned (concrete) dependencies to reproduce
+The third one is :pynwb:`requirements-dev.txt <blob/dev/requirements-dev.txt>`, which lists the pinned (concrete) dependencies to reproduce
 an entire development environment to use PyNWB, run PyNWB tests, check code style, compute coverage, and create test
 environments.
 
-The fourth one is requirements-doc.txt_, which lists the dependencies to generate the documentation for PyNWB.
-Both this file and `requirements.txt` are used by ReadTheDocs_ to initialize the local environment for Sphinx to run.
+The fourth one is :pynwb:`requirements-doc.txt <blob/dev/requirements-doc.txt>`, which lists the dependencies to generate the documentation for PyNWB.
+Both this file and :pynwb:`requirements.txt <blob/dev/requirements.txt>` are used by ReadTheDocs_ to initialize the local environment for Sphinx to run.
 
-The final one is within setup.py_, which contains a list of package dependencies and their version ranges allowed for
+The final one is within :pynwb:`setup.py <blob/dev/setup.py>`, which contains a list of package dependencies and their version ranges allowed for
 running PyNWB.
 
 In order to check the status of the required packages, requires.io_ is used to create a badge on the project
 README_. If all the required packages are up to date, a green badge appears.
 
 If some of the packages are outdated, see :ref:`update_requirements_files`.
 
-.. _requirements-min.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-min.txt
-.. _setup.py: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/setup.py
-.. _requirements.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements.txt
-.. _requirements-dev.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-dev.txt
-.. _requirements-doc.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-doc.txt
 .. _ReadTheDocs: https://readthedocs.org/projects/pynwb/
 .. _requires.io: https://requires.io/github/NeurodataWithoutBorders/pynwb/requirements/?branch=dev
 
@@ -82,7 +77,7 @@ Versioning and Releasing
 PyNWB uses versioneer_ for versioning source and wheel distributions. Versioneer creates a semi-unique release
 name for the wheels that are created. It requires a version control system (git in PyNWB's case) to generate a release
 name. After all the tests pass, CircleCI creates both a wheel (\*.whl) and source distribution (\*.tar.gz) for Python 3
-and uploads them back to GitHub as a release_. Versioneer makes it possible to get the source distribution from GitHub
+and uploads them back to GitHub as a :pynwb:`releases`. Versioneer makes it possible to get the source distribution from GitHub
 and create wheels directly without having to use a version control system because it hardcodes versions in the source
 distribution.
 

diff --git a/docs/source/update_requirements.rst b/docs/source/update_requirements.rst
@@ -7,15 +7,10 @@ How to Update Requirements Files
 
 The different requirements files introduced in :ref:`software_process` section are the following:
 
-* requirements.txt_
-* requirements-dev.txt_
-* requirements-doc.txt_
-* requirements-min.txt_
-
-.. _requirements.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements.txt
-.. _requirements-dev.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-dev.txt
-.. _requirements-doc.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-doc.txt
-.. _requirements-min.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-min.txt
+* :pynwb:`requirements.txt <blob/dev/requirements.txt>`
+* :pynwb:`requirements-dev.txt <blob/dev/requirements-dev.txt>`
+* :pynwb:`requirements-doc.txt <blob/dev/requirements-doc.txt>`
+* :pynwb:`requirements-min.txt <blob/dev/requirements-min.txt>`
 
 requirements.txt
 ================

diff --git a/src/pynwb/validate.py b/src/pynwb/validate.py
@@ -1,3 +1,4 @@
+"""Command line tool to Validate an NWB file against a namespace"""
 import os
 import sys
 from argparse import ArgumentParser