Add docs source

NeurodataWithoutBorders · Dec 6, 2024 · a231307 · a231307
1 parent 37187b6
commit a231307
Show file tree

Hide file tree

Showing 132 changed files with 8,397 additions and 0 deletions.
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -0,0 +1,74 @@
+/* arg formatting by line, taken from https://github.com/sphinx-doc/sphinx/issues/1514#issuecomment-742703082 */
+
+/* For general themes */
+div.body, .wy-nav-content {
+    max-width: 1000px; /* Set the content width */
+    margin: 0;         /* Remove auto-centering */
+    padding-left: 30;   /* Optional: Adjust padding */
+}
+
+/* For Read the Docs theme specifically */
+.wy-nav-content {
+    margin: 0; /* Remove centering (auto) */
+    padding-left: 30px; /* Align content to the left */
+}
+
+
+/*Newlines (\a) and spaces (\20) before each parameter*/
+dl.class em:not([class])::before {
+    content: "\a\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20";
+    white-space: pre;
+}
+
+/*Newline after the last parameter (so the closing bracket is on a new line)*/
+dl.class em:not([class]):last-of-type::after {
+    content: "\a";
+    white-space: pre;
+}
+
+/*To have blue background of width of the block (instead of width of content)*/
+dl.class > dt:first-of-type {
+    display: block !important;
+}
+
+.rst-content code.literal, .rst-content tt.literal {
+    color: #2b417e; /* Replace with your desired color */
+}
+.rst-content div[class^=highlight], .rst-content pre.literal-block {
+    margin: 1px 0 14px
+}
+
+.rst-content .section ol li>*, .rst-content .section ul li>*, .rst-content .toctree-wrapper ol li>*, .rst-content .toctree-wrapper ul li>*, .rst-content section ol li>*, .rst-content section ul li>* {
+    margin-top: 0px;
+}
+
+/* Ensure there is 10px spacing between nested list items at different levels*/
+.rst-content li > dl > dt {
+    margin-bottom: 10px;
+}
+.rst-content dd > ul > li {
+    margin-bottom: 10px;
+}
+.rst-content .section ol.simple li>*, .rst-content .section ol.simple li ol, .rst-content .section ol.simple li ul, .rst-content .section ul.simple li>*, .rst-content .section ul.simple li ol, .rst-content .section ul.simple li ul, .rst-content .toctree-wrapper ol.simple li>*, .rst-content .toctree-wrapper ol.simple li ol, .rst-content .toctree-wrapper ol.simple li ul, .rst-content .toctree-wrapper ul.simple li>*, .rst-content .toctree-wrapper ul.simple li ol, .rst-content .toctree-wrapper ul.simple li ul, .rst-content section ol.simple li>*, .rst-content section ol.simple li ol, .rst-content section ol.simple li ul, .rst-content section ul.simple li>*, .rst-content section ul.simple li ol, .rst-content section ul.simple li ul{
+    margin-bottom: 10px;
+}
+
+/* Improve padding and margins for function docstring section titles */
+.rst-content dd > dl > dt {
+    padding-left: 5px;
+    margin-top: 20px;
+    margin-bottom: 10px;
+}
+html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{
+    margin-top: 28px;
+    margin-bottom: 10px;
+}
+
+button.copybtn {
+    height:25px;
+    width:25px;
+    opacity: 0.5;
+    padding: 0;
+    border: none;
+    background: none;
+}
diff --git a/docs/source/_static/html/tutorials/UnitTimes.png b/docs/source/_static/html/tutorials/UnitTimes.png
diff --git a/docs/source/_static/html/tutorials/basicUsage.html b/docs/source/_static/html/tutorials/basicUsage.html
diff --git a/docs/source/_static/html/tutorials/behavior.html b/docs/source/_static/html/tutorials/behavior.html
diff --git a/docs/source/_static/html/tutorials/convertTrials.html b/docs/source/_static/html/tutorials/convertTrials.html
diff --git a/docs/source/_static/html/tutorials/dataPipe.html b/docs/source/_static/html/tutorials/dataPipe.html
diff --git a/docs/source/_static/html/tutorials/dimensionMapNoDataPipes.html b/docs/source/_static/html/tutorials/dimensionMapNoDataPipes.html
diff --git a/docs/source/_static/html/tutorials/dimensionMapWithDataPipes.html b/docs/source/_static/html/tutorials/dimensionMapWithDataPipes.html
diff --git a/docs/source/_static/html/tutorials/dynamic_tables.html b/docs/source/_static/html/tutorials/dynamic_tables.html
diff --git a/docs/source/_static/html/tutorials/dynamically_loaded_filters.html b/docs/source/_static/html/tutorials/dynamically_loaded_filters.html
diff --git a/docs/source/_static/html/tutorials/ecephys.html b/docs/source/_static/html/tutorials/ecephys.html
diff --git a/docs/source/_static/html/tutorials/ecephys.png b/docs/source/_static/html/tutorials/ecephys.png
diff --git a/docs/source/_static/html/tutorials/ecephys_01.png b/docs/source/_static/html/tutorials/ecephys_01.png
diff --git a/docs/source/_static/html/tutorials/ecephys_data_deps.png b/docs/source/_static/html/tutorials/ecephys_data_deps.png
diff --git a/docs/source/_static/html/tutorials/icephys.html b/docs/source/_static/html/tutorials/icephys.html
diff --git a/docs/source/_static/html/tutorials/images.html b/docs/source/_static/html/tutorials/images.html
diff --git a/docs/source/_static/html/tutorials/intro.html b/docs/source/_static/html/tutorials/intro.html
diff --git a/docs/source/_static/html/tutorials/ogen.html b/docs/source/_static/html/tutorials/ogen.html
diff --git a/docs/source/_static/html/tutorials/ophys.html b/docs/source/_static/html/tutorials/ophys.html
diff --git a/docs/source/_static/html/tutorials/ophys_tutorial_schematic.png b/docs/source/_static/html/tutorials/ophys_tutorial_schematic.png
diff --git a/docs/source/_static/html/tutorials/read_demo.html b/docs/source/_static/html/tutorials/read_demo.html
diff --git a/docs/source/_static/html/tutorials/remote_read.html b/docs/source/_static/html/tutorials/remote_read.html
diff --git a/docs/source/_static/html/tutorials/scratch.html b/docs/source/_static/html/tutorials/scratch.html
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+
+sys.path.append('sphinx_extensions')
+from docstring_processors import process_matlab_docstring
+
+def setup(app):
+    app.connect("autodoc-process-docstring", process_matlab_docstring)
+
+project = 'MatNWB'
+copyright = '2024, Neurodata Without Borders' # Todo: compute year
+author = 'Neurodata Without Borders'
+
+release = '2.7.0' # Todo: read from Contents.m
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.mathjax",  # or other extensions you may need
+    'sphinxcontrib.matlab', # generate docs for matlab functions
+    'sphinx.ext.autodoc', # autogenerate docs
+    'sphinx.ext.napoleon', # for parsing e.g google style parameter docstring
+    'sphinx.ext.viewcode',
+    'sphinx_copybutton',
+]
+
+# -- Options that are MATLAB specific ----------------------------------------
+
+highlight_language = 'matlab'
+
+primary_domain = "mat"
+
+# Get the absolute path of the script's directory
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+# Compute the absolute path two levels up from the script's directory
+matlab_src_dir = os.path.abspath(os.path.join(script_dir, '..', '..'))
+
+matlab_class_signature = True
+matlab_auto_link = "all"
+matlab_show_property_default_value = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ['_static']
+html_logo = os.path.join(matlab_src_dir, 'logo', 'logo_matnwb_small.png')
+html_theme_options = {
+    # "style_nav_header_background": "#AFD2E8"
+    "style_nav_header_background": "#000000"
+    }
+    #    'navigation_depth': 1,  # Adjust the depth as needed
+
+templates_path = ['_templates']
+exclude_patterns = []
+html_css_files = [
+    'css/custom.css',
+]
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,28 @@
+MatNWB documentation
+====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   pages/install_users
+   pages/tutorials/index
+   pages/overview_citing
+
+.. toctree::
+   :maxdepth: 2
+   :caption: MatNWB Documentation
+
+   pages/functions/index
+   pages/neurodata_types/core/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: For Developers
+
+   pages/developers
+   pages/developer/documentation/formatting_docstrings
diff --git a/docs/source/pages/developer/documentation/formatting_docstrings.rst b/docs/source/pages/developer/documentation/formatting_docstrings.rst
@@ -0,0 +1,176 @@
+Writing a Properly Documented MATLAB Docstring
+==============================================
+
+A well-documented MATLAB function should be structured to provide all necessary details about its purpose, usage, inputs, outputs, and examples in a clear and consistent format. This guide outlines the key sections and formatting rules to follow when documenting MATLAB functions, using ``NWBREAD`` as an example.
+
+1. Function Summary
+-------------------
+
+Provide a one-line summary of the function's purpose at the very beginning of the docstring. Use uppercase function names followed by a concise description.
+
+**Example**::
+
+   % NWBREAD - Read an NWB file.
+
+2. Syntax Section
+------------------
+
+Document the different ways the function can be called (function signatures). Include all variations and briefly describe their purpose. Each syntax line should start with a code literal and describe what it does.
+
+**Example**::
+
+   % Syntax:
+   %  nwb = NWBREAD(filename) Reads the nwb file at filename and returns an
+   %  NWBFile object representing its contents.
+   %
+   %  nwb = NWBREAD(filename, flags) Reads the nwb file using optional 
+   %  flags controlling the mode for how to read the file. See input
+   %  arguments for a list of available flags.
+   %
+   %  nwb = NWBREAD(filename, Name, Value) Reads the nwb file using optional 
+   %  name-value pairs controlling options for how to read the file.
+
+3. Input Arguments
+-------------------
+
+Provide a detailed description of all input arguments. Use the following format for each input:
+- Start with a ``-`` followed by the argument name.
+- Add the argument type in parentheses (e.g., ``(string)``).
+- Write a concise description on the same line or in an indented paragraph below.
+- For optional or additional parameters, list their sub-arguments as indented items.
+
+**Example**::
+
+   % Input Arguments:
+   %  - filename (string) - 
+   %    Filepath pointing to an NWB file.
+   % 
+   %  - flags (string) -
+   %    Flag for setting the mode for the NWBREAD operation. Available options are:
+   %    'ignorecache'. If the 'ignorecache' flag is used, classes for NWB data types
+   %    are not re-generated based on the embedded schemas in the file.
+   % 
+   %  - options (name-value pairs) -
+   %    Optional name-value pairs. Available options:
+   %  
+   %    - savedir (string) -
+   %      A folder to save generated classes for NWB types.
+
+4. Output Arguments
+--------------------
+
+Document all outputs of the function. Use a similar format as the input arguments:
+- Start with a ``-`` followed by the output name.
+- Add the output type in parentheses.
+- Provide a brief description.
+
+**Example**::
+
+   % Output Arguments:
+   %  - nwb (NwbFile) - Nwb file object
+
+5. Usage Examples
+------------------
+
+Provide practical examples of how to use the function. Each example should:
+- Start with "Example X - Description" and be followed by a colon (``::``).
+- Include MATLAB code blocks, indented with spaces.
+- Add comments in the code to explain each step if necessary.
+
+**Example**::
+
+   % Usage:
+   %  Example 1 - Read an NWB file::
+   %
+   %    nwb = nwbRead('data.nwb');
+   %
+   %  Example 2 - Read an NWB file without re-generating classes for NWB types::
+   %
+   %    nwb = nwbRead('data.nwb', 'ignorecache');
+   %
+   %  Note: This is a good option to use if you are reading several files
+   %  which are created of the same version of the NWB schemas.
+   %
+   %  Example 3 - Read an NWB file and generate classes for NWB types in the current working directory::
+   %
+   %    nwb = nwbRead('data.nwb', 'savedir', '.');
+
+6. See Also
+-----------
+
+Use the ``See also:`` section to reference related functions or objects. List each item separated by commas and include cross-references if applicable.
+
+**Example**::
+
+   % See also:
+   %   generateCore, generateExtension, NwbFile, nwbExport
+
+7. Formatting Tips
+-------------------
+
+- **Consistent Indentation**:
+  - Indent descriptions or additional information using two spaces.
+
+- **Bold Text**:
+  - Use ``**`` around key elements like argument names in the rendered documentation.
+
+- **Code Literals**:
+  - Use double backticks (``) for MATLAB code snippets in descriptions.
+
+- **Directives**:
+  - Use Sphinx-compatible directives for linking (``:class:``, ``:func:``, etc.) when writing in RST.
+
+8. Final Example
+-----------------
+
+**Complete Example**::
+
+   % NWBREAD - Read an NWB file.
+   %
+   % Syntax:
+   %  nwb = NWBREAD(filename) Reads the nwb file at filename and returns an
+   %  NWBFile object representing its contents.
+   %
+   %  nwb = NWBREAD(filename, flags) Reads the nwb file using optional 
+   %  flags controlling the mode for how to read the file. See input
+   %  arguments for a list of available flags.
+   %
+   %  nwb = NWBREAD(filename, Name, Value) Reads the nwb file using optional 
+   %  name-value pairs controlling options for how to read the file.
+   %
+   % Input Arguments:
+   %  - filename (string) - 
+   %    Filepath pointing to an NWB file.
+   % 
+   %  - flags (string) -
+   %    Flag for setting the mode for the NWBREAD operation. Available options are:
+   %    'ignorecache'. If the 'ignorecache' flag is used, classes for NWB data types
+   %    are not re-generated based on the embedded schemas in the file.
+   % 
+   %  - options (name-value pairs) -
+   %    Optional name-value pairs. Available options:
+   %  
+   %    - savedir (string) -
+   %      A folder to save generated classes for NWB types.
+   %
+   % Output Arguments:
+   %  - nwb (NwbFile) - Nwb file object
+   %
+   % Usage:
+   %  Example 1 - Read an NWB file::
+   %
+   %    nwb = nwbRead('data.nwb');
+   %
+   %  Example 2 - Read an NWB file without re-generating classes for NWB types::
+   %
+   %    nwb = nwbRead('data.nwb', 'ignorecache');
+   %
+   %  Note: This is a good option to use if you are reading several files
+   %  which are created of the same version of the NWB schemas.
+   %
+   %  Example 3 - Read an NWB file and generate classes for NWB types in the current working directory::
+   %
+   %    nwb = nwbRead('data.nwb', 'savedir', '.');
+   %
+   % See also:
+   %   generateCore, generateExtension, NwbFile, nwbExport
diff --git a/docs/source/pages/developers.rst b/docs/source/pages/developers.rst
@@ -0,0 +1,4 @@
+Developers
+=============
+
+hello
diff --git a/docs/source/pages/functions/NwbFile.rst b/docs/source/pages/functions/NwbFile.rst
@@ -0,0 +1,7 @@
+NwbFile
+=======
+
+.. mat:module:: .
+.. autoclass:: NwbFile
+    :members:
+    :show-inheritance:
diff --git a/docs/source/pages/functions/generateCore.rst b/docs/source/pages/functions/generateCore.rst
@@ -0,0 +1,5 @@
+generateCore
+============
+
+.. mat:module:: .
+.. autofunction:: generateCore
diff --git a/docs/source/pages/functions/generateExtension.rst b/docs/source/pages/functions/generateExtension.rst
@@ -0,0 +1,5 @@
+generateExtension
+=================
+
+.. mat:module:: .
+.. autofunction:: generateExtension
diff --git a/docs/source/pages/functions/index.rst b/docs/source/pages/functions/index.rst
@@ -0,0 +1,15 @@
+MatNWB Functions
+================
+
+These are the main functions of the MatNWB API
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Functions
+
+   nwbRead
+   NwbFile
+   nwbExport
+   generateCore
+   generateExtension
+   nwbClearGenerated
diff --git a/docs/source/pages/functions/nwbClearGenerated.rst b/docs/source/pages/functions/nwbClearGenerated.rst
@@ -0,0 +1,5 @@
+nwbClearGenerated
+=================
+
+.. mat:module:: .
+.. autofunction:: nwbClearGenerated