Add end-to-end extension example for extending LabMetaData (#59)

* Add extension and best practices draft * Refined structure of the example * Moved note * Add section lables for auto_api and custom_api * Added sphinx tabs dependency to allow writing of tabed examples * Add first full draft (minus MatLab) of the lab extension example * Remove source for extension example as this is now in its own repo * Fix broken links and includes * Add references from the extension example to the tutorial * Shortend publishing example and remove tabs in cases where we want to follow all steps * Minor spelling fix * Fix code indent in unit test example * Update labmetadata_extension.rst * Update labmetadata_extension.rst * Update labmetadata_extension.rst * Update labmetadata_extension.rst * Update labmetadata_extension.rst * Update labmetadata_extension.rst Co-authored-by: Ryan Ly <rly@lbl.gov>
NeurodataWithoutBorders · Oct 25, 2022 · fb7d269 · fb7d269
1 parent 5d84a79
commit fb7d269
Show file tree

Hide file tree

Showing 11 changed files with 386 additions and 5 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -30,6 +30,7 @@
     'sphinx.ext.extlinks',
     'sphinx_design',
     'sphinx_rtd_theme',
+    'sphinx_tabs.tabs',
 ]
 
 intersphinx_disabled_domains = ['std']

diff --git a/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst b/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst
@@ -1,3 +1,5 @@
+.. _extension-create:
+
 Creating an extension
 =====================
 

diff --git a/docs/source/extensions_tutorial/3_spec_api.rst b/docs/source/extensions_tutorial/3_spec_api.rst
@@ -1,3 +1,5 @@
+.. _extension-spec-api:
+
 The Spec API
 ------------
 

diff --git a/docs/source/extensions_tutorial/4_auto_api.rst b/docs/source/extensions_tutorial/4_auto_api.rst
@@ -1,5 +1,9 @@
+.. _extension-auto-api:
+
 Generating an API for an extension
------------------------------------------------------
+------------------------------------
+
+.. _extension-auto-matlabnapi:
 
 Generating a MatNWB API
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -13,6 +17,8 @@ In MatNWB, simply call ``generateExtension("path/to/extension/namespace.yaml");`
 .. note::
     As seen above, MatNWB will convert namespace names if they are not valid identifiers in MATLAB. See `Variable Names <https://www.mathworks.com/help/matlab/matlab_prog/variable-names.html>`_ for more information. In most cases, the conversion conforms with MATLAB's approach with `matlab.lang.makeValidName() <https://www.mathworks.com/help/matlab/ref/matlab.lang.makevalidname.html>`_
 
+.. _extension-auto-pythonapi:
+
 Generating a PyNWB API
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -36,7 +42,7 @@ created when you use the ``load_namespaces`` flag on :py:func:`~pynwb.NWBHDF5IO.
 Customizing automatically generated APIs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once these classes are generated, you can customize them by dynamically adding or replacing attributes/methods (a.k.a., monkey patching). 
+Once these classes are generated, you can customize them by dynamically adding or replacing attributes/methods (a.k.a., monkey patching).
 
 A typical example is adding methods. Let's say you wanted a method that could
 return data from only the first channel. You could add that method like this:
@@ -72,7 +78,7 @@ next section.
 .. tip::
     This approach is easy, but note your API will be locked to your specification. If you make changes to your
     specification there will be corresponding changes to the API, and this is likely to break existing code.
-    Also, monkey patches can be very confusing to someone who is not aware of them. Differences 
-    between the installed module and the actual behavior of the source code can lead to frustrated 
+    Also, monkey patches can be very confusing to someone who is not aware of them. Differences
+    between the installed module and the actual behavior of the source code can lead to frustrated
     developers. As such, this approach should be used with great care. In the
     next section we will show you how to create your own custom API that is more robust.
diff --git a/docs/source/extensions_tutorial/5_custom_api.rst b/docs/source/extensions_tutorial/5_custom_api.rst
@@ -1,3 +1,5 @@
+.. _extension-custom-api:
+
 Building a custom Python API for an extension
 =============================================
 

diff --git a/docs/source/extensions_tutorial/6_documenting_extension.rst b/docs/source/extensions_tutorial/6_documenting_extension.rst
@@ -1,3 +1,5 @@
+.. _extension-documentation:
+
 Documenting Extensions
 ----------------------
 

diff --git a/docs/source/extensions_tutorial/7_publishing_extensions.rst b/docs/source/extensions_tutorial/7_publishing_extensions.rst
@@ -1,3 +1,5 @@
+.. _extension-publishing:
+
 Publishing extensions
 ---------------------
 
@@ -11,10 +13,12 @@ As illustrated in the figure, the publication process is divided into three main
 releases via PyPI, and 3) open publication of the extension to the community via the
 :ndx-catalog:`NDX Catalog <>`.
 
+.. _extension-publishing-github:
+
 Open Source: Releasing your extension Git repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-1. Before publishing your licence online you should add a license file. Permissive licenses should be used if possible. A `BSD license <https://opensource.org/licenses/BSD-3-Clause>` is recommended.
+1. Before publishing your extension online you should add a license file. Permissive licenses should be used if possible. A `BSD license <https://opensource.org/licenses/BSD-3-Clause>` is recommended.
 2. Modify ``README.md`` at the root directory of your extension repo to describe the extension for interested developers and users.
 3. The first step to publishing your extension then is to make your Git repository accessible online
    via GitHub, or any other public Git hosting service of your choice. To publish your extension
@@ -32,6 +36,8 @@ Open Source: Releasing your extension Git repository
    extensions repositories. However, users may chose to use other services (e.g.,  GitLab or Bitbucket)
    to share their sources.
 
+.. _extension-publishing-pypi:
+
 Open Access: Releasing your extension on PyPI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -48,6 +54,8 @@ To make your extension installable for users via pip and manage public releases
     python setup.py sdist bdist_wheel
     twine upload dist/*
 
+.. _extension-publishing-ndxcatalog:
+
 Open Publication: Publishing your extension on the NDX Catalog
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/source/extensions_tutorial/8_examples.rst b/docs/source/extensions_tutorial/8_examples.rst
@@ -0,0 +1,10 @@
+.. _extension-nwb-examples:
+
+Examples
+--------
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    extension_examples/labmetadata_extension