Bootstrap docs from template (#21)

* Add bug report template

* Add more templates

* Adding deploy to pypi

* First stab at running CI tests

* Unit tests only for Python 3.13

* Fix libgit

* Whitespace

* Should work now

* Explain why we need this

* Stick to python 3.12 for now

* Add codecov, improve pyproject toml

* Install test environment

* Improve readme with autogenerated screenshots :)

* Add more screenshots

* Adding in quarto pip tests requirements

* Quarto via pip

* Add pandocfilters

* Move towards trusted publishing

* Autofixing

* Panflutes

* Typo

* Flute, not flutes

* Not necessary

* Use quarto GH action to setup quarto

* Don't enforce quarto version

* Fix v8 options

* update release workflow

* Update pre-commit

* autoformat

* run rich codex automatically

* disable codecov for now; can revisit later

* attempt fix rich codex autocommits

* Pre-commit

* Bootstrap docs from template

* Try fix rich

* test pre-commit action

* Try fix rich

* test pre-commit action

* Generate new screengrabs with rich-codex

* Rich codex to separate PR

* rich codex separate PR

* Commit pre-commit changes even when pre-commit failed (intended for autofixing)

* Apply automatic changes

* trigger ci

* Bootstrap docs from template

* Try fix rich

* Apply automatic changes

* cleanup

* Fix sphinx build

* Add docs action

* test

* update workflows

* update workflows

* test

* fix reference to changelog

* fix contributing

* use hatch envs

* migrate pre-commit config

* update contributing guide

---------

Co-authored-by: Alexander Peltzer <[email protected]>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: grst <[email protected]>

.github/workflows/build.yml

@@ -0,0 +1,29 @@
+name: Check Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: "**/pyproject.toml"
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip wheel twine build
+      - name: Build package
+        run: python -m build
+      - name: Check package
+        run: twine check --strict dist/*.whl

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: "Build docs using sphinx"
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    # also run on 'closed' to clean up the github pages dir
+    types:
+        - opened
+        - reopened
+        - synchronize
+        - closed
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  docs:
+    name: "Build Docs"
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: "Install hatch"
+        run: pip install hatch
+
+      - name: "Build docs with Sphinx"
+        run: hatch run docs:build -W --keep-going
+
+      - name: Deploy preview
+        if: github.event_name == 'pull_request'
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/_build/html
+
+      - name: Deploy docs
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html
+          branch: gh-pages
+          clean-exclude: pr-preview/
+          force: false

.github/workflows/unit_tests.yml

@@ -15,7 +15,8 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: ["3.12"]
+        # test minimum and maximum supported python version
+        python-version: ["3.10", "3.13"]
 
     env:
       # GitHub currently has 4 cores available for Linux runners
@@ -38,7 +39,7 @@ jobs:
         run: sudo apt-get install -y libgit2-dev pandoc
 
       - name: "Install DSO"
-        run: pip install -e '.[test]'
+        run: pip install '.[test]'
 
       - name: "Run unit tests"
         run: pytest -vv tests -n ${{ env.worker_cores }} --cov=dso --cov-report=xml

.gitignore

@@ -8,6 +8,9 @@ buck-out/
 __pycache__/
 .*cache/
 
+# UV
+uv.lock
+
 # Distribution / packaging
 /dist/
 

.pre-commit-config.yaml

@@ -2,8 +2,8 @@ fail_fast: false
 default_language_version:
   python: python3
 default_stages:
-  - commit
-  - push
+  - pre-commit
+  - pre-push
 minimum_pre_commit_version: 2.16.0
 repos:
 #   - repo: https://github.com/pre-commit/mirrors-prettier

docs/CHANGELOG.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,4 @@
+/* Reduce the font size in data frames - See https://github.com/scverse/cookiecutter-scverse/issues/193 */
+div.cell_output table.dataframe {
+    font-size: 0.8em;
+}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,61 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. add toctree option to make autodoc generate the pages
+
+.. autoclass:: {{ objname }}
+
+{% block attributes %}
+{% if attributes %}
+Attributes table
+~~~~~~~~~~~~~~~~
+
+.. autosummary::
+{% for item in attributes %}
+    ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block methods %}
+{% if methods %}
+Methods table
+~~~~~~~~~~~~~
+
+.. autosummary::
+{% for item in methods %}
+    {%- if item != '__init__' %}
+    ~{{ name }}.{{ item }}
+    {%- endif -%}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes_documentation %}
+{% if attributes %}
+Attributes
+~~~~~~~~~~
+
+{% for item in attributes %}
+
+.. autoattribute:: {{ [objname, item] | join(".") }}
+{%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block methods_documentation %}
+{% if methods %}
+Methods
+~~~~~~~
+
+{% for item in methods %}
+{%- if item != '__init__' %}
+
+.. automethod:: {{ [objname, item] | join(".") }}
+{%- endif -%}
+{%- endfor %}
+
+{% endif %}
+{% endblock %}

docs/api.md

@@ -0,0 +1,9 @@
+# API
+
+```{eval-rst}
+.. module:: dso
+.. currentmodule:: dso
+
+.. autosummary::
+    :toctree: generated
+```

docs/conf.py

@@ -0,0 +1,130 @@
+# 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
+
+# -- Path setup --------------------------------------------------------------
+import sys
+from datetime import datetime
+from importlib.metadata import metadata
+from pathlib import Path
+
+HERE = Path(__file__).parent
+sys.path.insert(0, str(HERE / "extensions"))
+
+
+# -- Project information -----------------------------------------------------
+
+# NOTE: If you installed your project in editable mode, this might be stale.
+#       If this is the case, reinstall it to refresh the metadata
+info = metadata("dso-core")
+project_name = info["Name"]
+author = info["Author"]
+copyright = f"{datetime.now():%Y}, {author}."
+version = info["Version"]
+urls = dict(pu.split(", ") for pu in info.get_all("Project-URL"))
+repository_url = urls["Source"]
+
+# The full version, including alpha/beta/rc tags
+release = info["Version"]
+
+bibtex_bibfiles = ["references.bib"]
+templates_path = ["_templates"]
+nitpicky = True  # Warn about broken links
+needs_sphinx = "4.0"
+
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "grst",
+    "github_repo": project_name,
+    "github_version": "main",
+    "conf_py_path": "/docs/",
+}
+
+# -- 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_nb",
+    "sphinx_copybutton",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.bibtex",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.mathjax",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "sphinxext.opengraph",
+    *[p.stem for p in (HERE / "extensions").glob("*.py")],
+]
+
+autosummary_generate = True
+autodoc_member_order = "groupwise"
+default_role = "literal"
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_use_rtype = True  # having a separate entry generally helps readability
+napoleon_use_param = True
+myst_heading_anchors = 6  # create anchors for h1-h6
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "html_admonition",
+]
+myst_url_schemes = ("http", "https", "mailto")
+nb_output_stderr = "remove"
+nb_execution_mode = "off"
+nb_merge_streams = True
+typehints_defaults = "braces"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+# 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", ".DS_Store", "**.ipynb_checkpoints"]
+
+
+# -- 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 = "sphinx_book_theme"
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
+
+html_title = project_name
+
+html_theme_options = {
+    "repository_url": repository_url,
+    "use_repository_button": True,
+    "path_to_docs": "docs/",
+    "navigation_with_keys": False,
+}
+
+pygments_style = "default"
+
+nitpick_ignore = [
+    # If building the documentation fails because of a missing link that is outside your control,
+    # you can add an exception to this list.
+    #     ("py:class", "igraph.Graph"),
+]