Limited scope docs PR

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## [0.4.4] (November 7, 2023)
+
+- Additional documentation. #686
+
 ## [0.4.3] (November 7, 2023)
 
 - Migrate `config` helper scripts to Spyglass codebase. #662
@@ -95,6 +99,8 @@
 - Allow creation and linkage of device metadata from YAML #400
 - Move helper functions to utils directory #386
 
+[0.4.4]: https://github.com/LorenFrankLab/spyglass/releases/tag/0.4.4
+[0.4.3]: https://github.com/LorenFrankLab/spyglass/releases/tag/0.4.3
 [0.4.2]: https://github.com/LorenFrankLab/spyglass/releases/tag/0.4.2
 [0.4.1]: https://github.com/LorenFrankLab/spyglass/releases/tag/0.4.1
 [0.4.0]: https://github.com/LorenFrankLab/spyglass/releases/tag/0.4.0

docs/build-docs.sh

@@ -9,6 +9,8 @@ cp ./CHANGELOG.md ./docs/src/
 cp ./LICENSE ./docs/src/LICENSE.md
 mkdir -p ./docs/src/notebooks
 cp ./notebooks/*ipynb ./docs/src/notebooks/
+cp ./notebooks/*md ./docs/src/notebooks/
+cp ./docs/src/notebooks/README.md ./docs/src/notebooks/index.md
 cp -r ./notebook-images ./docs/src/notebooks/
 cp -r ./notebook-images ./docs/src/
 

docs/mkdocs.yml

@@ -47,16 +47,19 @@ nav:
   - Home: index.md
   - Installation: installation.md
   - Miscellaneous:
+      - Overview: misc/index.md
       - FigURL: misc/figurl_views.md
       - Session Groups: misc/session_groups.md
       - Insert Data: misc/insert_data.md
       - Merge Tables: misc/merge_tables.md
+      - Database Management: misc/database_management.md
   - Tutorials:
-      - Overview: notebooks/README.md
+      - Overview: notebooks/index.md
       - General:
           - Setup: notebooks/00_Setup.ipynb
           - Insert Data: notebooks/01_Insert_Data.ipynb
           - Data Sync: notebooks/02_Data_Sync.ipynb
+          - Merge Tables: notebooks/03_Merge_Tables.ipynb
       - Ephys:
           - Spike Sorting: notebooks/10_Spike_Sorting.ipynb
           - Curation: notebooks/11_Curation.ipynb
@@ -101,8 +104,6 @@ plugins:
             group_by_category: false
             line_length: 80
             docstring_style: numpy
-      # watch:
-      # - src/spyglass/
   - literate-nav:
       nav_file: navigation.md
   - exclude-search:

docs/src/api/index.md

@@ -0,0 +1,27 @@
+# API Docs
+
+The files in this directory are automatically generated from the docstrings in
+the source code. They include descriptions of each of the DataJoint tables and
+other classes/methods within Spyglass.
+
+These docs are updated any time a new release is made or a tag is
+pushed to the repository.
+
+<!--
+TODO: add section indexes
+https://github.com/oprypin/mkdocs-gen-files/issues/2
+- [cli](./cli/)
+- [common](./common/)
+- [data_import](./data_import)
+- [decoding](./decoding)
+- [figurl_views](./figurl_views)
+- [lfp](./lfp)
+- [lock](./lock)
+- [position](./position)
+- [position_linearization](./position_linearization)
+- [ripple](./ripple)
+- [settings.py](./settings.py)
+- [sharing](./sharing)
+- [spikesorting](./spikesorting)
+- [utils](./utils)
+--->

docs/src/api/make_pages.py

@@ -4,15 +4,36 @@
 from pathlib import Path
 
 import mkdocs_gen_files
+from mkdocs.utils import log
+
+ignored_stems = ["__init__", "_version"]
+
+added = 0
+add_limit = None
 
 nav = mkdocs_gen_files.Nav()
-for path in sorted(Path("src").glob("**/*.py")):
-    if path.stem == "__init__" or "cython" in path.stem:
+for path in sorted(Path("src/spyglass/").glob("**/*.py")):
+    if path.stem in ignored_stems or "cython" in path.stem:
         continue
-    with mkdocs_gen_files.open(f"api/{path.with_suffix('')}.md", "w") as f:
+    rel_path = path.relative_to("src/spyglass")
+    with mkdocs_gen_files.open(f"api/{rel_path.with_suffix('')}.md", "w") as f:
         module_path = ".".join([p for p in path.with_suffix("").parts])
         print(f"::: {module_path}", file=f)
-    nav[path.parts] = f"{path.with_suffix('')}.md"
+    nav[rel_path.parts] = f"{rel_path.with_suffix('')}.md"
+
+    if add_limit is not None:
+        if added < add_limit:
+            log.warning(f"Generated {rel_path.with_suffix('')}.md")
+            added += 1
+        else:
+            break
+
+if add_limit is not None:
+    from IPython import embed
+
+    embed()
+
 
 with mkdocs_gen_files.open("api/navigation.md", "w") as nav_file:
+    nav_file.write("* [Overview](../api/index.md)\n")
     nav_file.writelines(nav.build_literate_nav())

docs/src/index.md

@@ -1,24 +1,38 @@
 # Spyglass
 
-**Spyglass** is a data analysis framework that facilitates the
-storage, analysis, and sharing of neuroscience data to support
-reproducible research. It is designed to be interoperable with the NWB
-format and integrates open-source tools into a coherent framework.
+**Spyglass** is a data analysis framework that facilitates the storage,
+analysis, and sharing of neuroscience data to support reproducible research. It
+is designed to be interoperable with the NWB format and integrates open-source
+tools into a coherent framework.
 
-## Installation
+## Getting Started
 
-To install to this project, see [Installation](./installation.md).
+This site hosts both [installation instructions](./installation.md) and
+[tutorials](./notebooks/index.md) to help you get started with Spyglass. We
+recommend running the notebooks yourself. They can be downloaded from GitHub
+[here](https://github.com/LorenFrankLab/spyglass).
 
-## Contributing
+## Diving Deeper
 
-For contribution instructions see [How to Contribute](./contribute.md)
+The [API Reference](./api/index.md) provides a detailed description of all the
+tables and class functions in Spyglass via python docstrings. Potential
+contributors should also read the [Developer Guide](./contribute.md). Those
+interested in in hosting a Spyglass instance for their own data should read the
+[database management guide](./misc/database_management.md).
+
+We have a series of additional docs under the [misc](./misc/index.md) folder
+that may be helpful. Our [changelog](./CHANGELOG.md) highlights the changes that
+have been made to Spyglass over time and the [copyright](./LICENSE.md) page
+contains license information.
 
 ## Citing Spyglass
 
-Kyu Hyun Lee, Eric Denovellis, Ryan Ly, Jeremy Magland, Jeff Soules,
-Alison Comrie, Jennifer Guidera, Rhino Nevers, Daniel Gramling, Philip
-Adenekan, Ji Hyun Bak, Emily Monroe, Andrew Tritt, Oliver Rübel, Thinh
-Nguyen, Dimitri Yatsenko, Joshua Chu, Caleb Kemere, Samuel Garcia,
-Alessio Buccino, Emily Aery Jones, Lisa Giocomo, and Loren Frank.
-'Spyglass: A Data Analysis Framework for Reproducible and Shareable
-Neuroscience Research.' (2022) Society for Neuroscience, San Diego, CA.
+Kyu Hyun Lee, Eric Denovellis, Ryan Ly, Jeremy Magland, Jeff Soules, Alison
+Comrie, Jennifer Guidera, Rhino Nevers, Daniel Gramling, Philip Adenekan, Ji
+Hyun Bak, Emily Monroe, Andrew Tritt, Oliver Rübel, Thinh Nguyen, Dimitri
+Yatsenko, Joshua Chu, Caleb Kemere, Samuel Garcia, Alessio Buccino, Emily Aery
+Jones, Lisa Giocomo, and Loren Frank. 'Spyglass: A Data Analysis Framework for
+Reproducible and Shareable Neuroscience Research.' (2022) Society for
+Neuroscience, San Diego, CA.
+
+<!-- TODO: Convert ccf file and insert here  -->