Improve Documentation Grouping and Features (#539)

* refactor documentation and make it prettier

* Refactor dependencies by grouping documentation-specific packages.

* Add `sphinx-design` to Sphinx extensions list

Author: tasansal

docs/reference.md renamed to docs/api_reference.md

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

docs/usage.md renamed to docs/cli_usage.md

@@ -1,4 +1,4 @@
-# Usage
+# CLI Usage
 
 ## Ingestion and Export
 
@@ -68,11 +68,11 @@ 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:
@@ -104,10 +104,10 @@ 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:
@@ -136,11 +136,11 @@ 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

docs/conf.py

@@ -1,31 +1,66 @@
 """Sphinx configuration."""
 
+# -- Project information -----------------------------------------------------
+
 project = "MDIO"
 author = "TGS"
 copyright = "2023, TGS"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx_click",
     "sphinx_copybutton",
     "myst_nb",
+    "sphinx_design",
 ]
 
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    "jupyter_execute",
+    ".DS_Store",
+    "**.ipynb_checkpoints",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "zarr": ("https://zarr.readthedocs.io/en/stable/", None),
+}
+
+pygments_style = "vs"
+pygments_dark_style = "material"
+
 autodoc_typehints = "description"
 autodoc_typehints_format = "short"
 autodoc_member_order = "groupwise"
-autoclass_content = "both"
+autoclass_content = "class"
 autosectionlabel_prefix_document = True
 
 html_theme = "furo"
 
 myst_number_code_blocks = ["python"]
 myst_heading_anchors = 2
+myst_words_per_minute = 80
 myst_enable_extensions = [
+    "colon_fence",
     "linkify",
     "replacements",
     "smartquotes",
+    "attrs_inline",
 ]
 
 # sphinx-copybutton configurations

docs/index.md

@@ -6,24 +6,38 @@ end-before: <!-- github-only -->
 
 [apache 2.0 license]: license
 [contributor guide]: contributing
-[command-line usage]: usage
-[api reference]: reference
+[command-line usage]: cli_usage
+[api reference]: api_reference
 [installation instructions]: installation
 
 ```{toctree}
----
-hidden:
-maxdepth: 1
----
+:hidden:
+:caption: Getting Started
+
 installation
-notebooks/quickstart
-notebooks/creation
-notebooks/compression
-notebooks/rechunking
-usage
-reference
+cli_usage
+```
+
+```{toctree}
+:hidden:
+:caption: Learning and Support
+
+tutorials/index
+api_reference
+```
+
+```{toctree}
+:hidden:
+:caption: Community and Contribution
+
 contributing
 Code of Conduct <codeofconduct>
+```
+
+```{toctree}
+:hidden:
+:caption: Additional Resources
+
 License <license>
 Changelog <https://github.com/TGSAI/mdio-python/releases>
 ```

docs/installation.md

@@ -1,4 +1,4 @@
-# Install Instructions
+# Installation
 
 There are different ways to install MDIO:
 

docs/requirements.txt

@@ -1,6 +1,7 @@
 furo==2024.8.6
-sphinx==8.2.1
+linkify-it-py==2.0.3
+myst-nb==1.2.0
+sphinx==8.2.3
 sphinx-click==6.0.0
 sphinx-copybutton==0.5.2
-myst-nb==1.2.0
-linkify-it-py==2.0.3
+sphinx-design==0.6.1

docs/notebooks/compression.ipynb renamed to docs/tutorials/compression.ipynb

@@ -6,6 +6,13 @@
    "source": [
     "# Seismic Data Compression\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "In this page we will be showing compression performance of _MDIO_.\n",
     "\n",
     "For demonstration purposes, we will use one of the Volve dataset stacks.\n",

docs/notebooks/creation.ipynb renamed to docs/tutorials/creation.ipynb

@@ -10,6 +10,13 @@
    "source": [
     "# Create a New MDIO File From Scratch\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "Here we will create an empty MDIO file and populate its fields.\n",
     "\n",
     "```{warning}\n",

docs/tutorials/index.md

@@ -0,0 +1,9 @@
+# Tutorials
+
+```{toctree}
+:hidden:
+quickstart
+creation
+compression
+rechunking
+```

docs/notebooks/quickstart.ipynb renamed to docs/tutorials/quickstart.ipynb

@@ -10,6 +10,13 @@
    "source": [
     "# Get Started in 10 Minutes\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "In this page we will be showing basic capabilities of MDIO.\n",
     "\n",
     "For demonstration purposes, we will download the Teapot Dome open-source dataset. The dataset details and licensing can be found at the [SEG Wiki](https://wiki.seg.org/wiki/Teapot_dome_3D_survey).\n",
@@ -118,7 +125,7 @@
     }
    },
    "source": [
-    "It only took a few seconds to ingest, since this is a very small file. \n",
+    "It only took a few seconds to ingest, since this is a very small file.\n",
     "\n",
     "However, MDIO scales up to TB (that's ~1,000 GB) sized volumes!\n",
     "\n",
@@ -413,7 +420,7 @@
     }
    },
    "source": [
-    "We can extract a dimension by name, and see its values. \n",
+    "We can extract a dimension by name, and see its values.\n",
     "\n",
     "The `Dimension` has `name` and `coords` that returns a string and a numpy array."
    ]
@@ -657,7 +664,7 @@
    "source": [
     "We can query headers for the whole dataset very quickly because they are separated from the seismic wavefield.\n",
     "\n",
-    "Let's get all the headers for X and Y coordinates in this dataset. \n",
+    "Let's get all the headers for X and Y coordinates in this dataset.\n",
     "\n",
     "As mentioned before, X Coordinates map to `inline` and Y Coordinates map to `crossline` due to non-standard Teapot data.\n",
     "\n",
@@ -854,7 +861,7 @@
    "source": [
     "## MDIO to SEG-Y Conversion\n",
     "\n",
-    "Finally, let's demonstrate going back to SEG-Y. \n",
+    "Finally, let's demonstrate going back to SEG-Y.\n",
     "\n",
     "We will use the convenient `mdio_to_segy` function and write it out as a round-trip file."
    ]