Add sphinx for py-oxbow documentation

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: Build the docs
+        run: |
+          pip install --upgrade hatch
+          hatch run docs:build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: docs/_build/html

py-oxbow/docs/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from __future__ import annotations
+
+# Warning: do not change the path here. To use autodoc, you need to install the
+# package first.
+
+# -- Project information -----------------------------------------------------
+
+project = "oxbow"
+copyright = "2023, Oxbow Developers"
+author = "Oxbow Developers"
+
+
+# -- 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 = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = []
+
+# Include both markdown and rst files
+source_suffix = [".rst", ".md"]
+
+# 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", "**.ipynb_checkpoints", "Thumbs.db", ".DS_Store", ".env"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path: list[str] = []
+
+
+# -- Extension configuration -------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]

py-oxbow/docs/index.rst

@@ -0,0 +1,26 @@
+oxbow
+=====
+
+Read specialized bioinformatic file formats as data frames in R, Python, and more.
+
+File formats create a lot of friction for computational biologists. Oxbow is a data unification layer that aims to improve data accessibility and ease of high-performance analytics.
+
+Data I/O is handled in Rust with features exposed to Python and R via Apache Arrow.
+
+Learn more in our recent `blog post <https://open.substack.com/pub/lifeinbytes/p/breaking-out-of-bioinformatic-data-silos?r=jue12&utm_campaign=post&utm_medium=web>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :caption: Contents
+   :glob:
+
+
+API docs
+--------
+
+.. automodule:: oxbow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:

py-oxbow/pyproject.toml

@@ -31,5 +31,18 @@ dependencies = [
     "pysam",
 ]
 
+[tool.hatch.envs.docs]
+dependencies = [
+    "furo",
+    "myst_parser>=0.13",
+    "sphinx>=4.0",
+    "sphinx-autobuild",
+    "sphinx-book-theme>=0.1.0",
+    "sphinx_copybutton",
+]
+[tool.hatch.envs.docs.scripts]
+build = "sphinx-build docs docs/_build/html"
+serve = "sphinx-autobuild docs docs/_build/html"
+
 [tool.ruff.isort]
 known-first-party = ["oxbow"]