Added tutorials to documentation

docs/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?= -b html -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = ./_build/
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Clean build directory
+clean:
+	rm -rf $(BUILDDIR)
+
+# Build HTML with automatic clean
+html: clean
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -1,17 +1,22 @@
 # Documentation
 
-To build the documentation locally:
+To build the documentation, ensure you have all the necessary plugins installed:
 
 ```bash
-# Install documentation dependencies
 pip install -e . --group docs
+```
+
+then run locally using `Make` (with working directory being the `docs/` directory):
 
-# Clean any previous local runs first
-rm -r ./docs/_build
+```bash
+make html
+```
 
-# Build
-sphinx-build -b html -W --keep-going docs ./docs/_build
+or without `Make`:
 
-# View the built documentation
-# Open ./docs/_build/html/index.html in your favorite web browser
+```bash
+rm -rf _build
+sphinx-build -b html -W --keep-going . _build
 ```
+
+Then view the built documentation by opening `docs/_build/html/index.html` in your favorite web browser.

docs/_static/custom.css

@@ -0,0 +1,9 @@
+/* The primary sphinx copybutton for code blocks. */
+button.copybtn {
+   opacity: 1;
+}
+
+/* Confusingly, this is the identifier for the toggleprompt button. */
+span.copybutton {
+   opacity: 0;
+}

docs/conf.py

@@ -1,10 +1,10 @@
 """Configuration file for the Sphinx documentation builder."""
 
+import pathlib
 import sys
-from pathlib import Path
 
 # Add source directory to path for autodoc
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "src"))
 
 # Project details
 project = "nwb2bids"
@@ -18,6 +18,9 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_tabs.tabs",
+    "sphinx_copybutton",
+    "sphinx_toggleprompt",  # Used to control >>> behavior in the doctests
+    "myst_parser",  # For including Markdown files to be rendered as RST
 ]
 
 # HTML configuration
@@ -41,6 +44,9 @@
     "doc_path": "docs",
 }
 
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
 # Format signatures for better readability
 autodoc_typehints = "signature"
 autodoc_typehints_format = "short"
@@ -53,9 +59,36 @@
 # Disable sidebars for specific sections
 html_sidebars = {
     'user_guide': [],
+    'tutorials': [],
     "developer_guide": [],
 }
 
+# Toggleprompt
+toggleprompt_offset_right = 45  # This controls the position of the prompt (>>>) for the conversion gallery
+toggleprompt_default_hidden = "true"
+
+# Copybutton
+copybutton_exclude = '.linenos, .gp'  # This avoids copying prompt (>>>) in the conversion gallery (issue #1465)
+
+# MyST
+myst_enable_extensions = [
+    "colon_fence",      # ::: fences
+    "deflist",          # Definition lists
+    "fieldlist",        # Field lists
+    "html_admonition",  # HTML-style admonitions
+    "html_image",       # HTML images
+    "replacements",     # Text replacements
+    "smartquotes",      # Smart quotes
+    "strikethrough",    # ~~strikethrough~~
+    "substitution",     # Variable substitutions
+    "tasklist",         # Task lists
+]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+
 # --------------------------------------------------
 # Extension configuration
 # --------------------------------------------------

docs/conftest.py

@@ -0,0 +1,29 @@
+"""Configuration file for the doctests."""
+import json
+import pathlib
+import typing
+
+import pytest
+
+import nwb2bids
+
+
+# Doctest directories
+@pytest.fixture(autouse=True)
+def add_data_space(doctest_namespace: dict[str, typing.Any], tmp_path: pathlib.Path):
+    doctest_namespace["path_to_some_directory"] = pathlib.Path(tmp_path)
+
+    nwb2bids.testing.generate_ephys_tutorial(mode="file")
+    nwb2bids.testing.generate_ephys_tutorial(mode="dataset")
+
+    tutorial_directory = nwb2bids.testing.get_tutorial_directory() / "ephys_tutorial_file"
+    additional_metadata_file_path = tutorial_directory / "metadata.json"
+
+    additional_metadata = {
+        "dataset_description": {
+            "Name": "My Custom BIDS Dataset",
+            "BIDSVersion": "1.8.0",
+            "Authors": ["First Last", "Second Author"]
+        }
+    }
+    additional_metadata_file_path.write_text(data=json.dumps(obj=additional_metadata))

docs/developer_guide.rst

@@ -105,16 +105,5 @@ TODO
 Documentation
 -------------
 
-The documentation is hosted on ReadTheDocs.org and can be built locally by first installing the ``docs`` group:
-
-.. code-block:: bash
-
-   pip install -e ".[docs]"
-
-Then, from the root of the repository, run:
-
-.. code-block:: bash
-
-    sphinx-build -b html -W --keep-going docs ./docs/_build/
-
-And launch the resulting ``./docs/_build/index.html`` file in your web browser.
+.. include:: README.md
+   :parser: myst_parser.sphinx_

docs/index.rst

@@ -4,6 +4,7 @@
    :hidden:
 
    user_guide
+   tutorials
    developer_guide
    api/index