feat: Implement SDS admonitions for docs site (#1401)

* feat: Implement SDS admonitions for docs site * fix: Dark mode admonitions, move examples to admonitions * feat: Admonition styling to match SDS * chore: Fix FAQ accordion styling to follow SDS
chanzuckerberg · Jan 17, 2025 · b211efc · b211efc
1 parent 3947969
commit b211efc
Show file tree

Hide file tree

Showing 7 changed files with 170 additions and 49 deletions.
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -314,11 +314,19 @@ dl.class > dd > dl:nth-child(27) {
 
 .czi-faq.admonition > summary.admonition-title {
   background-color: var(--md-default-bg-color);
-  padding-left: 14px;
+  padding-left: 14px !important;
+  padding-top: 8px !important;
+  padding-bottom: 8px !important;
+  font-weight: 600;
 }
 
 .czi-faq.admonition > summary.admonition-title::before {
   content: none;
+  margin-right: 10px;
+}
+
+.czi-faq.admonition > summary.admonition-title::after {
+  background-color: #6C6C6C;
 }
 
 .md-typeset .admonition, .md-typeset details {
@@ -327,6 +335,96 @@ dl.class > dd > dl:nth-child(27) {
   border-bottom: 0.01px solid var(--md-default-fg-color--lightest);
 }
 
+/* Admonitions */
+.md-typeset .admonition-title {
+  font-weight: 600;
+  padding: 0 0 0 44px !important;
+}
+
+.md-typeset .admonition-title:before {
+  top: 0;
+  height: 24px;
+  width: 24px;
+}
+
+[data-md-color-scheme="slate"] {
+  .md-typeset .czi-info.admonition>.admonition-title:before {
+    background-color: rgb(162, 201, 255) !important;
+  }
+
+  .md-typeset .czi-warning.admonition>.admonition-title:before {
+    background-color: rgb(229, 188, 99) !important;
+  }
+}
+
+div.czi-info.admonition,
+div.czi-warning.admonition {
+  border-radius: 4px;
+  margin-top: 12px !important;
+  margin-bottom: 12px !important;
+  padding-top: 12px;
+  padding-bottom: 12px;
+  border: 0;
+}
+
+/* Dark mode admonitions */
+[data-md-color-scheme="default"] {
+  div.czi-info.admonition, div.czi-warning.admonition {
+    color: black !important;
+  }
+
+  .md-typeset .czi-info>.admonition-title,
+  .md-typeset .admonition.czi-info {
+    background-color: #e2eeff; /* light blue */
+    border-color: #E2EEFF !important;
+  }
+
+  .md-typeset .czi-warning>.admonition-title,
+  .md-typeset .admonition.czi-warning {
+    background-color: #FFF3E1; /* light yellow */
+    border-color: #FFF3E1 !important;
+  }
+}
+
+[data-md-color-scheme="slate"] {
+  div.czi-info.admonition,
+  div.czi-warning.admonition {
+    color: white !important;
+  }
+
+  .md-typeset .czi-info>.admonition-title,
+  .md-typeset .admonition.czi-info {
+    background-color: rgb(15, 29, 74); /* dark blue */
+    border-color: rgb(15, 29, 74) !important;
+  }
+
+  .md-typeset .czi-warning>.admonition-title,
+  .md-typeset .admonition.czi-warning {
+    background-color: rgb(54, 27, 7); /* dark brown */
+    border-color: rgb(54, 27, 7) !important;
+  }
+}
+
+.md-typeset .czi-info.admonition>p:not(.admonition-title),
+.md-typeset .czi-warning.admonition>p:not(.admonition-title) {
+  margin-left: 32px;
+  margin-top: 6px;
+  margin-bottom: 0 !important;
+}
+
+.md-typeset .czi-info.admonition>div,
+.md-typeset .czi-warning.admonition>div {
+  margin-left: 32px;
+}
+
+.czi-info.admonition .highlight-shell .highlight>pre code,
+.czi-info.admonition>p code,
+.czi-warning.admonition .highlight-shell .highlight>pre code,
+.czi-warning.admonition>p code {
+  background-color: #F3F3F3 !important;
+  color: black;
+}
+
 /* Figure/video captions */
 .md-typeset figcaption {
   min-width: 75%;

diff --git a/docs/_static/img/IconExclamationMarkCircleLarge.svg b/docs/_static/img/IconExclamationMarkCircleLarge.svg
diff --git a/docs/conf.py b/docs/conf.py
@@ -121,6 +121,25 @@
     ("py:.*", dict(include_fields_in_toc=False)),
 ]
 
+sphinx_immaterial_custom_admonitions = [
+    {
+        "name": "czi-info",
+        "title": "Info",
+        "color": "#3867FA",
+        "icon": "IconExclamationMarkCircleLarge",
+        "override": True,
+    },
+    {
+        "name": "czi-warning",
+        "title": "Warning",
+        "color": "#F5A623",
+        "icon": "IconExclamationMarkCircleLarge",
+        "override": True,
+    },
+]
+
+sphinx_immaterial_icon_path = ["./_static/img"]
+
 # -- Options for myst -------------------------------------------------
 myst_enable_extensions = ['colon_fence']
 myst_heading_anchors = 4

diff --git a/docs/cryoet_data_portal_docsite_examples.md b/docs/cryoet_data_portal_docsite_examples.md
@@ -3,8 +3,9 @@
 
 Below are code snippets for completing various tasks using the Python Client API. Have an example you'd like to share with the community? Submit a [GitHub issue](https://github.com/chanzuckerberg/cryoet-data-portal/issues) and include "Example:" in your title.
 
-<details open>
-  <summary>Query by annotated object or Gene Ontology terms using owlready2 library</summary>
+:::{admonition} Query by annotated object or Gene Ontology terms using owlready2 library
+:class: czi-faq
+:collapsible: open
 
 Find all membrane annotations, including when the annotation has a subclass of membrane.
 
@@ -35,11 +36,11 @@ object_runs = set([po.run.id for po in portal_objects])
 # Datasets that contain annotations with that term
 object_datasets = set([po.run.dataset_id for po in portal_objects])
 ```
+:::
 
-</details>
-
-<details>
-  <summary>List zarr file contents using the zarr package and HTTPS link</summary>
+:::{admonition} List zarr file contents using the zarr package and HTTPS link
+:class: czi-faq
+:collapsible:
 
 Stream data using https
 
@@ -63,11 +64,11 @@ for i in g.attrs["multiscales"][0]["datasets"]:
   x = zarr.open(f"{url}/{path}")
   print(x.info_items())
 ```
+:::
 
-</details>
-
-<details>
-  <summary>List zarr-file contents using the ome-zarr package and HTTPS link</summary>
+:::{admonition} List zarr-file contents using the ome-zarr package and HTTPS link
+:class: czi-faq
+:collapsible:
 
 Stream data using https
 
@@ -89,11 +90,11 @@ reader = Reader(parse_url(url))
 nodes = list(reader())
 nodes[0].data
 ```
+:::
 
-</details>
-
-<details>
-  <summary>List zarr-file contents using the zarr package and S3 link</summary>
+:::{admonition} List zarr-file contents using the zarr package and S3 link
+:class: czi-faq
+:collapsible:
 
 Stream data via S3
 
@@ -109,11 +110,11 @@ tomo = Tomogram.find(client, [Tomogram.run.dataset_id == 10000])[0]
 g = zarr.open_group(tomo.s3_omezarr_dir, mode='r')
 g.info_items()
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Open a tomogram array using the zarr package and HTTPS link</summary>
+:::{admonition} Open a tomogram array using the zarr package and HTTPS link
+:class: czi-faq
+:collapsible:
 
 Stream data using https
 
@@ -127,11 +128,11 @@ tomo = Tomogram.find(client, [Tomogram.run.dataset_id == 10000])[0]
 
 g = zarr.open_array(f"{tomo.https_omezarr_dir}/0", mode='r')
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Find all annotation files available in ZARR format from a dataset</summary>
+:::{admonition} Find all annotation files available in ZARR format from a dataset
+:class: czi-faq
+:collapsible:
 
 Use as training data for a segmentation model
 
@@ -147,11 +148,11 @@ ret = AnnotationFile.find(client, [
     AnnotationFile.format == 'zarr'
 ])
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Open a Point-annotation file and stream the contents from S3</summary>
+:::{admonition} Open a Point-annotation file and stream the contents from S3
+:class: czi-faq
+:collapsible:
 
 Use as training data for a particle picking model
 
@@ -175,11 +176,11 @@ with fs.open(ret[0].s3_path) as pointfile:
   for point in ndjson.reader(pointfile):
       print(f"A {name} at {point['location']['x']}, {point['location']['y']}, {point['location']['z']}")
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Find all datasets that have movie frames available</summary>
+:::{admonition} Find all datasets that have movie frames available
+:class: czi-faq
+:collapsible:
 
 Start processing the raw data
 
@@ -192,11 +193,11 @@ client = Client()
 # Find all datasets, that have 1 or more frame files
 datasets_with_frames = Dataset.find(client, [Dataset.runs.frames.id != None])
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Find all tomograms with voxel spacing below a threshold</summary>
+:::{admonition} Find all tomograms with voxel spacing below a threshold
+:class: czi-faq
+:collapsible:
 
 Select data of a specific resolution
 
@@ -215,11 +216,11 @@ s3mrc = [t.s3_mrc_scale0 for t in tomos]
 # S3 URIs for Zarrs
 s3zarr = [t.s3_omezarr_dir for t in tomos]
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Compute statistics on the portal data using the API client</summary>
+:::{admonition} Compute statistics on the portal data using the API client
+:class: czi-faq
+:collapsible:
 
 Find how many runs there are in total for a given species
 
@@ -251,11 +252,11 @@ plt.bar(sorted_by_run.keys(), sorted_by_run.values(), color='g')
 plt.xticks(rotation=30, ha='right')
 plt.show()
 ```
+:::
 
-</details>
-
-<details>
-  <summary>Download the movie stacks of one run using S3 file streaming</summary>
+:::{admonition} Download the movie stacks of one run using S3 file streaming
+:class: czi-faq
+:collapsible:
 
 Start processing from raw data
 
@@ -284,5 +285,4 @@ for frame in frames_list:
   frame_path = frame.s3_path
   fs.get_file(frame_path, os.path.join(outdir, os.path.basename(frame_path)))
 ```
-
-</details>
+:::
diff --git a/docs/cryoet_data_portal_docsite_landing.md b/docs/cryoet_data_portal_docsite_landing.md
@@ -81,6 +81,6 @@ Some of the data used in this work was provided by the group(s) of Julia Mahamid
 | Dataset name | 10000 | 10001 | 10004 |
 | Acknowledgement | [doi:10.1038/s41592-022-01746-2](http://doi.org/doi:10.1038/s41592-022-01746-2) | [doi:10.1038/s41592-022-01746-2](http://doi.org/doi:10.1038/s41592-022-01746-2) | [doi:10.1101/2023.04.28.538734](https://www.biorxiv.org/content/10.1101/2023.04.28.538734v1) |
 
-:::{note}
+:::{czi-info} Note
 Segmentation experts and developers are also encouraged to get in touch with the data providers if they feel they have developed a useful tool that might help to process the entirety of the datasets (which are much larger than the subsets provided for the portal) more efficiently or effectively.
 :::
diff --git a/docs/cryoet_data_portal_docsite_napari.md b/docs/cryoet_data_portal_docsite_napari.md
@@ -26,7 +26,7 @@ From here, installing the latest version of napari with `pip` should work for mo
 pip install -U "napari[all]"
 ```
 
-:::{attention}
+:::{czi-warning} Attention
 For ARM macOS (Apple Silicon), pre-built packages of Qt5 are not available on PyPI, so the above command will fail.
 Instead, either install Qt6 separately with the following two commands
 
@@ -71,7 +71,7 @@ Instead of opening files manually in napari, you can write Python to automate th
 The following code finds all tomograms with a particular annotator and minimum tomogram size
 using the Python client and opens the first one in napari.
 
-:::{attention}
+:::{czi-warning} Attention
 This example depends on installing the napari-ome-zarr plugin mentioned above.
 :::
 

diff --git a/docs/cryoet_data_portal_docsite_quick_start.md b/docs/cryoet_data_portal_docsite_quick_start.md
@@ -82,7 +82,7 @@ Below are 3 examples of common operations you can do with the API. Check out the
 
 To illustrate the relationships among the classes in the Portal, below is a loop that iterates over all datasets in the portal, then all runs per dataset, then all tomograms per run and outputs the name of each object.
 
-:::{attention}
+:::{czi-info} Note
 This loop is impractical! It iterates over all data in the Portal. It is simply for demonstrative purposes and should not be included in efficient code.
 :::