docs: switch to pydata theme and mds

docs/source/cli.rst → docs/source/cli/index.rst

@@ -11,6 +11,10 @@ CLI
   :prog: momics add
   :nested: full
 
+.. click:: momics.cli.query:query
+  :prog: momics query
+  :show-nested:
+
 .. click:: momics.cli.ls:ls
   :prog: momics ls
   :show-nested:

docs/source/conf.py

@@ -20,7 +20,6 @@
 project = info["Name"]
 author = "Jacques Serizay"
 copyright = f"2023-{datetime.now():%Y}, {author}."
-copyright = f"{datetime.now():%Y}, {author}."
 release = info["Version"]
 version = release.rsplit(".", maxsplit=1)[0]
 
@@ -38,20 +37,21 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx_click.ext",
-    "recommonmark",
+    "myst_parser",
 ]
 
+myst_enable_extensions = ["colon_fence", "substitution"]
+myst_heading_anchors = 2
+source_suffix = [".rst", ".md"]
+
 autosummary_generate = True
 numpydoc_show_class_members = True
 napoleon_use_rtype = True
 autodoc_typehints = "description"
 autodoc_class_signature = "separated"
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-source_suffix = {
-    ".rst": "restructuredtext",
-    ".md": "markdown",
-}
+
 pygments_style = "sphinx"
 todo_include_todos = False
 master_doc = "index"
@@ -61,24 +61,53 @@
 
 # html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+html_logo = "_static/logo.svg"
+html_favicon = "_static/logo.svg"
+html_sourcelink_suffix = ""
+html_last_updated_fmt = ""  # to reveal the build date in the pages meta
 htmlhelp_basename = "momicsdoc"
 html_last_updated_fmt = "%b %d, %Y"
 html_title = "momics"
-html_theme = "furo"
+
+# html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
 html_theme_options = {
-    "source_repository": "https://github.com/js2264/momics/",
-    "source_branch": "devel",
-    "source_directory": "docs/",
-    "footer_icons": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/js2264/momics",
-            "html": """
-                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
-                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
-                </svg>
-            """,
-            "class": "",
-        },
-    ],
+    "use_edit_page_button": True,
+    "external_links": "",
+    "github_url": "https://github.com/js2264/momics/",
+    "show_prev_next": False,
+    "search_bar_text": "Search the docs ...",
+    "navigation_with_keys": False,
+    "collapse_navigation": False,
+    "navigation_depth": 4,
+    "show_nav_level": 2,
+    "show_toc_level": 2,
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    "secondary_sidebar_items": {
+        "**/*": ["page-toc", "edit-this-page", "sourcelink"],
+        "examples/no-sidebar": [],
+    },
+    "pygments_light_style": "a11y-high-contrast-light",
+    "pygments_dark_style": "a11y-high-contrast-dark",
+    "back_to_top_button": False,
+}
+html_context = {
+    "github_url": "https://github.com/js2264/momics/",
+    "github_user": "js2264",
+    "github_repo": "momics",
+    "github_version": "devel",
+    "doc_path": "",
 }
+html_static_path = ["_static"]
+
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_member_order = "groupwise"
+
+# -- Options for autoapi -------------------------------------------------------
+autoapi_type = "python"
+autoapi_dirs = ["../src/pydata_sphinx_theme"]
+autoapi_keep_files = True
+autoapi_root = "api"
+autoapi_member_order = "groupwise"

docs/source/index.md

@@ -0,0 +1,32 @@
+---
+html_theme.sidebar_secondary.remove: true
+---
+
+<!-- momics documentation master file, created by
+sphinx-quickstart on Mon Jul 29 11:05:32 2024.
+You can adapt this file completely to your liking, but it should at least
+contain the root `toctree` directive. -->
+
+# momics
+
+`momics` is a Python support library for .momics files. 
+
+The `momics` package aims to facilitate:
+
+* Creation: ingestion of genomic files into `momics` files;
+* Querying: sequential and range query patterns and tabular and array retrieval;
+* Scalable: cloud-native, out-of-core operations on the data;
+* Export: data export.
+
+Follow `momics` development on [GitHub](https://github.com/js2264/momics).
+
+```{toctree}
+:caption: Table of content
+:maxdepth: 2
+:hidden:
+
+user_guide/index
+api/index
+cli/index
+```
+

docs/source/index.rst

@@ -17,13 +17,10 @@ The `momics` package aims to facilitate:
 
 Follow `momics` development on `GitHub <https://github.com/js2264/momics>`_.
 
-Contents:
-
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    quickstart
    cli.rst
    api.rst
-   glossary.rst
-   py-modindex.rst

docs/source/user_guide/api.md

@@ -0,0 +1,4 @@
+# Python API
+
+See the [API reference](../api/index) for more information.
+

docs/source/user_guide/cli.md

@@ -0,0 +1,5 @@
+# Command line interface (CLI)
+
+The `momics` package includes command-line tools for creating, querying and manipulating `.momics` files.
+
+See the [CLI reference](../cli/index) for more information.

docs/source/user_guide/get-started.md

@@ -0,0 +1,40 @@
+# Get started
+
+## Installation
+
+With python `3.8` and higher, you can install `momics`  from [PyPI](https://pypi.org/project/momics) using `pip`.
+
+```
+pip install momics
+```
+
+The following requirements should be automatically installed:
+
+- `tiledb`, `pyarrow`, `numpy`, `scipy`, `pandas`, `pyBigWig`.
+
+```{tip}
+We highly recommend using the `conda` package manager to install scientific 
+packages like these. To get `conda`, you can download either the 
+full [Anaconda](https://www.continuum.io/downloads) Python distribution 
+which comes with lots of data science software or the minimal 
+[Miniconda](http://conda.pydata.org/miniconda.html) distribution 
+which is just the standalone package manager plus Python. 
+
+In the latter case, you can install `momics` and all its dependencies as follows:
+
+    conda install bioconda::momics
+
+```
+
+## Workflow
+
+```
+momics create hg19.momics 
+momics add chroms hg19.chrom.sizes
+momics add tracks a=sample1.bw b=sample2.bw c=sample3.bw hg19.momics 
+momics tree hg19.momics
+momics ls --table chroms hg19.momics
+momics ls --table tracks hg19.momics
+momics query --query "I:10-1000" hg19.momics
+momics extract --out a.bw hg19.momics
+```

docs/source/user_guide/index.md

@@ -0,0 +1,22 @@
+---
+html_theme.sidebar_primary.remove: true
+---
+
+# User guide
+
+```{danger}
+This package is still under active development, and we make no promises
+about the stability of any specific class, function, etc.
+Pin versions if you're worried about breaking changes!
+```
+
+## Content 
+
+```{toctree}
+:maxdepth: 3
+
+get-started
+api
+cli
+```
+

pyproject.toml

@@ -79,6 +79,8 @@ docs = [
     "sphinx-autobuild",
     "sphinx-click",
     "furo",
+    "pydata-sphinx-theme",
+    "myst-parser",
 ]
 
 [tool.ruff]