Merge pull request #645 from FZJ-INM1-BDA/doc_showcase_paper_nbs

Doc showcase paper nbs

Author: AhmetNSimsek

README.rst

@@ -20,6 +20,14 @@ It aims to facilitate programmatic and reproducible incorporation of brain parce
 It supports both discretely labelled and statistical (probabilistic) parcellation maps, which can be used to assign brain regions to spatial locations and image signals, to retrieve region-specific neuroscience datasets from multiple online repositories, and to sample information from high-resolution image data. 
 The datasets anchored to brain regions address features of molecular, cellular and architecture as well as connectivity, and are complemented with live queries to external repositories as well as dynamic extraction from "big" image volumes such as the 20 micrometer BigBrain model.
 
+``siibra`` hides much of the complexity that would be required to collect and interact with the individual parcellations, templates and data repositories.
+By encapsulating many aspects of interacting with different maps and reference templates spaces, it also minimizes common errors like misinterpretation of coordinates from different reference spaces, confusing label indices of brain regions, or using inconsistent versions of parcellation maps. 
+It aims to provide a safe way of using maps defined across multiple spatial scales for reproducible analysis.
+
+.. intro-end
+
+.. about-start
+
 ``siibra`` was developed in the frame of the `Human Brain Project <https://humanbrainproject.eu>`__ for accessing the `EBRAINS
 human brain atlas <https://ebrains.eu/service/human-brain-atlas>`__. 
 It stores most of its contents as sustainable and open datasets in the `EBRAINS Knowledge Graph <https://kg.ebrains.eu>`__, and is designed to support the `OpenMINDS metadata standards <https://github.com/HumanBrainProject/openMINDS_SANDS>`__. 
@@ -28,11 +36,7 @@ In fact, the viewer is a good resource for exploring ``siibra``\ ’s core funct
 Feature queries in ``siibra`` are parameterized by data modality and anatomical location, while the latter could be a brain region, brain parcellation, or location in reference space. 
 Beyond the explorative focus of ``siibra-explorer``, the Python library supports a range of data analysis functions suitable for typical neuroscience workflows.
 
-``siibra`` hides much of the complexity that would be required to collect and interact with the individual parcellations, templates and data repositories.
-By encapsulating many aspects of interacting with different maps and reference templates spaces, it also minimizes common errors like misinterpretation of coordinates from different reference spaces, confusing label indices of brain regions, or using inconsistent versions of parcellation maps. 
-It aims to provide a safe way of using maps defined across multiple spatial scales for reproducible analysis.
-
-.. intro-end
+.. about-end
 
 .. getting-started-start
 

docs/_static/siibra-logo-darkmode.png

@@ -1,5 +1,5 @@
-..  _mainconcepts:
-Elements of an atlas in siibra
+..  _glossary:
+Glossary
 ==============================
 
 A typical brain atlas consists of 

docs/concepts.rst

@@ -19,7 +19,7 @@
 print("sphinx-book-theme:", sphinx_book_theme.__version__)
 print("sphinx-autopackagesummary", sphinx_autopackagesummary.__version__)
 
-os.environ['SIIBRA_LOG_LEVEL'] = "ERROR"
+os.environ["SIIBRA_LOG_LEVEL"] = "ERROR"
 sys.path.insert(0, os.path.abspath(".."))
 print("Path:", sys.path)
 
@@ -28,7 +28,7 @@ def is_allen_api_microarray_service_available():
     import requests
 
     # see https://community.brain-map.org/t/human-brain-atlas-api/2876
-    microarray_test_url = "http://api.brain-map.org/api/v2/data/query.json?criteria= service::human_microarray_expression[probes$eq1023146,1023147][donors$eq15496][structures$eq9148]"
+    microarray_test_url = "http://api.brain-map.org/api/v2/data/query.json?criteria=service::human_microarray_expression[probes$eq1023146,1023147][donors$eq15496][structures$eq9148]"
     try:
         response = requests.get(microarray_test_url).json()
     except requests.RequestException:
@@ -86,6 +86,8 @@ def is_allen_api_microarray_service_available():
     "sphinx_copybutton",  # adds a copy button for code fields
     "sphinxcontrib.images",  # adds lightbox to images
     "sphinxcontrib.mermaid",  # embed Mermaid graphs including flowcharts, sequence diagrams, gantt diagrams, etc.
+    "sphinx_design",
+    "sphinx_togglebutton",
 ]
 
 run_stale_examples = True
@@ -129,7 +131,7 @@ def is_allen_api_microarray_service_available():
 
 # Mappings
 intersphinx_mapping = {
-    "mainconcepts": ("../concepts.html", None),
+    "glossary": ("../concepts.html", None),
     "matplotlib": ("https://matplotlib.org/", None),
     "nilearn": ("https://nilearn.github.io/stable/index.html", None),
     "nibabel": ("https://nipy.org/nibabel/", None),
@@ -167,13 +169,15 @@ def is_allen_api_microarray_service_available():
         "../examples/03_data_features",
         "../examples/04_locations",
         "../examples/05_anatomical_assignment",
+        "../examples/tutorials",
     ],
     "gallery_dirs": [
         "examples/01_atlases_and_parcellations",
         "examples/02_maps_and_templates",
         "examples/03_data_features",
         "examples/04_locations",
         "examples/05_anatomical_assignment",
+        "examples/tutorials",
     ],
     "filename_pattern": r"^.*.py",  # which files to execute and include their outputs
     "capture_repr": ("_repr_html_", "__repr__"),
@@ -220,7 +224,7 @@ def is_allen_api_microarray_service_available():
 html_theme_options = {
     "logo": {
         "image_light": "_static/siibra-python.jpeg",
-        "image_dark": "_static/siibra-python.jpeg",
+        "image_dark": "_static/siibra-logo-darkmode.png",
     },
     "repository_url": "https://github.com/FZJ-INM1-BDA/siibra-python",
     "use_repository_button": True,