diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..38bfd6a --- /dev/null +++ b/.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 diff --git a/py-oxbow/docs/conf.py b/py-oxbow/docs/conf.py new file mode 100644 index 0000000..5a880c5 --- /dev/null +++ b/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", +] diff --git a/py-oxbow/docs/index.rst b/py-oxbow/docs/index.rst new file mode 100644 index 0000000..9b5d964 --- /dev/null +++ b/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 `_. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + :caption: Contents + :glob: + + +API docs +-------- + +.. automodule:: oxbow + :members: + :undoc-members: + :show-inheritance: + :inherited-members: diff --git a/py-oxbow/pyproject.toml b/py-oxbow/pyproject.toml index def49bb..51869b5 100644 --- a/py-oxbow/pyproject.toml +++ b/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"]