fix doc build warnings and some syntax

Author: tasansal

docs/api_reference.md

@@ -1,4 +1,4 @@
-# Reference
+# API Reference
 
 ## Readers / Writers
 

docs/cli_usage.md

@@ -68,27 +68,27 @@ Credentials can be automatically fetched from pre-authenticated AWS CLI.
 See [here](https://s3fs.readthedocs.io/en/latest/index.html#credentials) for the order `s3fs`
 checks them. If it is not pre-authenticated, you need to pass `--storage-options-{input,output}`.
 
-**Prefix:**  
+**Prefix:**
 `s3://`
 
-**Storage Options:**  
-`key`: The auth key from AWS  
+**Storage Options:**
+`key`: The auth key from AWS
 `secret`: The auth secret from AWS
 
 Using UNIX:
 
 ```shell
-mdio segy import \
-  path/to/my.segy \
-  s3://bucket/prefix/my.mdio \
-  --header-locations 189,193 \
-  --storage-options-output '{"key": "my_super_private_key", "secret": "my_super_private_secret"}'
+$ mdio segy import \
+    path/to/my.segy \
+    s3://bucket/prefix/my.mdio \
+    --header-locations 189,193 \
+    --storage-options-output '{"key": "my_super_private_key", "secret": "my_super_private_secret"}'
 ```
 
 Using Windows (note the extra escape characters `\`):
 
-```console
-mdio segy import \
+```shell
+$ mdio segy import \
   path/to/my.segy \
   s3://bucket/prefix/my.mdio \
   --header-locations 189,193 \
@@ -104,30 +104,30 @@ checks them. If it is not pre-authenticated, you need to pass `--storage-options
 GCP uses [service accounts](https://cloud.google.com/iam/docs/service-accounts) to pass
 authentication information to APIs.
 
-**Prefix:**  
+**Prefix:**
 `gs://` or `gcs://`
 
-**Storage Options:**  
+**Storage Options:**
 `token`: The service account JSON value as string, or local path to JSON
 
 Using a service account:
 
 ```shell
-mdio segy import \
-  path/to/my.segy \
-  gs://bucket/prefix/my.mdio \
-  --header-locations 189,193 \
-  --storage-options-output '{"token": "~/.config/gcloud/application_default_credentials.json"}'
+$ mdio segy import \
+    path/to/my.segy \
+    gs://bucket/prefix/my.mdio \
+    --header-locations 189,193 \
+    --storage-options-output '{"token": "~/.config/gcloud/application_default_credentials.json"}'
 ```
 
 Using browser to populate authentication:
 
 ```shell
-mdio segy import \
-  path/to/my.segy \
-  gs://bucket/prefix/my.mdio \
-  --header-locations 189,193 \
-  --storage-options-output '{"token": "browser"}'
+$ mdio segy import \
+    path/to/my.segy \
+    gs://bucket/prefix/my.mdio \
+    --header-locations 189,193 \
+    --storage-options-output '{"token": "browser"}'
 ```
 
 ### Microsoft Azure
@@ -136,19 +136,19 @@ There are various ways to authenticate with Azure Data Lake (ADL).
 See [here](https://github.com/fsspec/adlfs#details) for some details.
 If ADL is not pre-authenticated, you need to pass `--storage-options-{input,output}`.
 
-**Prefix:**  
+**Prefix:**
 `az://` or `abfs://`
 
-**Storage Options:**  
-`account_name`: Azure Data Lake storage account name  
+**Storage Options:**
+`account_name`: Azure Data Lake storage account name
 `account_key`: Azure Data Lake storage account access key
 
 ```shell
-mdio segy import \
-  path/to/my.segy \
-  az://bucket/prefix/my.mdio \
-  --header-locations 189,193 \
-  --storage-options-output '{"account_name": "myaccount", "account_key": "my_super_private_key"}'
+$ mdio segy import \
+    path/to/my.segy \
+    az://bucket/prefix/my.mdio \
+    --header-locations 189,193 \
+    --storage-options-output '{"account_name": "myaccount", "account_key": "my_super_private_key"}'
 ```
 
 ### Advanced Cloud Features

docs/data_models/chunk_grids.md

@@ -133,7 +133,9 @@ conceptual and visually not to scale.
 
 ```{eval-rst}
 .. autopydantic_model:: RegularChunkGrid
+
 ----------
+
 .. autopydantic_model:: RegularChunkShape
 ```
 
@@ -143,7 +145,9 @@ conceptual and visually not to scale.
 
 ```{eval-rst}
 .. autopydantic_model:: RectilinearChunkGrid
+
 ----------
+
 .. autopydantic_model:: RectilinearChunkShape
 ```
 

docs/data_models/compressors.md

@@ -65,12 +65,16 @@ For more details about compression modes, see [ZFP Documentation].
 
 ```{eval-rst}
 .. autopydantic_model:: Blosc
+
 ----------
+
 .. autoclass:: BloscAlgorithm()
     :members:
     :undoc-members:
     :member-order: bysource
+
 ----------
+
 .. autoclass:: BloscShuffle()
     :members:
     :undoc-members:
@@ -84,7 +88,9 @@ For more details about compression modes, see [ZFP Documentation].
 
 ```{eval-rst}
 .. autopydantic_model:: ZFP
+
 ----------
+
 .. autoclass:: ZFPMode()
     :members:
     :undoc-members:

docs/data_models/data_types.md

@@ -22,6 +22,7 @@ Scalar types are used to represent numbers and boolean values in MDIO arrays.
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
+
    ScalarType
 ```
 
@@ -125,6 +126,7 @@ efficient access and manipulation.
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
+
    StructuredType
    StructuredField
 ```
@@ -248,7 +250,9 @@ This will yield an in-memory or on-disk struct that looks like this (for each el
 
 ```{eval-rst}
 .. autopydantic_model:: StructuredType
+
 ----------
+
 .. autopydantic_model:: StructuredField
 ```
 

noxfile.py

@@ -237,7 +237,7 @@ def docs_build(session: Session) -> None:
 def docs(session: Session) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     ignore = [
-        "docs/jupyter_execute/tutorials/quickstart.ipynb",
+        "docs/jupyter_execute/*",
     ]
     args = ["--open-browser", "docs", "docs/_build", "--ignore", *ignore]
     args = session.posargs or args

poetry.lock

@@ -42,7 +42,7 @@
 following, per the SEG-Y Rev1 standard:
 
 \b
---header-names inline,crossline
+`--header-names inline,crossline
 --header-locations 189,193
 --header-types int32,int32
 
@@ -142,7 +142,7 @@
     help="Option to add grid overrides.",
     type=JSON,
 )
-def segy_import(
+def segy_import(  # noqa: PLR0913
     segy_path: str,
     mdio_path: str,
     header_locations: list[int],
@@ -155,7 +155,7 @@ def segy_import(
     storage_options_output: dict[str, Any],
     overwrite: bool,
     grid_overrides: dict[str, Any],
-):
+) -> None:
     """Ingest SEG-Y file to MDIO.
 
     SEG-Y format is explained in the "segy" group of the command line
@@ -224,6 +224,7 @@ def segy_import(
 
     Usage:
 
+        \b
         Below are some examples of ingesting standard SEG-Y files per
         the SEG-Y Revision 1 and 2 formats.
 
@@ -269,8 +270,9 @@ def segy_import(
     wrapped channel numbers. Note the missing byte location and type
     for the "cable" index.
 
-
     Usage:
+
+        \b
         3D Seismic Shot Data (Byte Locations Vary):
         Let's assume streamer number does not exist but there are
         800 channels per cable.
@@ -279,8 +281,7 @@ def segy_import(
         --header-names shot,cable,chan
         --header-types int32,None,int32
         --chunk-size 8,2,256,512
-        --grid-overrides '{"ChannelWrap": True, "ChannelsPerCable": 800,
-                           "CalculateCable": True}'
+        --grid-overrides '{"ChannelWrap": True, "ChannelsPerCable": 800, "CalculateCable": True}'
 
         \b
         If we do have cable numbers in the headers, but channels are still
@@ -294,6 +295,7 @@ def segy_import(
         For shot gathers with channel numbers and wrapped channels, no
         grid overrides are necessary.
 
+        \b
         In cases where the user does not know if the input has unwrapped
         channels but desires to store with wrapped channel index use:
         --grid-overrides '{"AutoChannelWrap": True}'
@@ -343,7 +345,7 @@ def segy_import(
         --header-types int32,int16,int32
         --chunk-size 8,2,256,512
         --grid-overrides '{"HasDuplicates": True}'
-    """
+    """  # noqa: D301
     from mdio import segy_to_mdio
 
     segy_to_mdio(
@@ -397,7 +399,7 @@ def segy_export(
     access_pattern: str,
     storage_options: dict[str, Any],
     endian: str,
-):
+) -> None:
     """Export MDIO file to SEG-Y.
 
     SEG-Y format is explained in the "segy" group of the command line