docs: add documentation (#29)

.github/workflows/checks.yml → .github/workflows/checks.yaml

@@ -36,3 +36,23 @@ jobs:
         env:
           WAGSTAILS_TEST_ENV: true
         run: python3 -m pytest tests/
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ secrets.SPHINX_GITHUB_CHANGELOG_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install '.[docs]'
+
+      - name: Attempt docs build
+        working-directory: ./docs
+        run: make html

.gitignore

@@ -161,3 +161,5 @@ cython_debug/
 
 # Test temp directory
 tests/tmp/
+
+docs/build

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/source/conf.py

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 The Wagner/Chaudhari Laboratories at the Institute for Genomic Medicine
+Copyright (c) 2023-2024 The Wagner/Chaudhari Laboratories at the Institute for Genomic Medicine
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,8 +1,28 @@
-# WagsTAILS
+# Wags-TAILS
 
 *Technology-Assisted Information Loading and Structure (TAILS) for Wagnerds.*
 
-This tool provides data acquisition and access utilities for several projects developed by the Wagner Lab.
+[![image](https://img.shields.io/pypi/v/wags-tails.svg)](https://pypi.python.org/pypi/wags-tails)
+[![image](https://img.shields.io/pypi/l/wags-tails.svg)](https://pypi.python.org/pypi/wags-tails)
+[![image](https://img.shields.io/pypi/pyversions/wags-tails.svg)](https://pypi.python.org/pypi/wags-tails)
+[![Actions status](https://github.com/genomicmedlab/wags-tails/workflows/checks.yaml/badge.svg)](https://github.com/genomicmedlab/wags-tails/actions/workflows/checks.yaml)
+
+<!-- description -->
+This tool provides data acquisition and access utilities for several projects developed by the [Wagner Lab](https://www.nationwidechildrens.org/specialties/institute-for-genomic-medicine/research-labs/wagner-lab). It designates a storage location in user-space where external data files can be saved, and provides methods to download and update them when available.
+<!-- /description -->
+
+It is currently used in:
+
+* [Thera-Py](https://github.com/cancervariants/therapy-normalization)
+* [Gene Normalizer](https://github.com/cancervariants/gene-normalization)
+* [Disease Normalizer](https://github.com/cancervariants/disease-normalization)
+* and more!
+
+---
+
+**[Documentation](https://wags-tails.readthedocs.io/stable/)** · [Installation](https://wags-tails.readthedocs.io/stable/install.html) · [Usage](https://wags-tails.readthedocs.io/stable/usage.html) · [API reference](https://wags-tails.readthedocs.io/stable/reference/index.html)
+
+---
 
 ## Installation
 
@@ -12,6 +32,8 @@ Install from PyPI:
 python3 -m pip install wags_tails
 ```
 
+---
+
 ## Usage
 
 Data source classes provide a `get_latest()` method that acquires the most recent available data file and returns a pathlib.Path object with its location:
@@ -20,8 +42,8 @@ Data source classes provide a `get_latest()` method that acquires the most recen
 >>> from wags_tails.mondo import MondoData
 >>> m = MondoData()
 >>> m.get_latest(force_refresh=True)
-Downloading mondo.owl: 100%|█████████████████| 171M/171M [00:28<00:00, 6.23MB/s]
-PosixPath('/Users/genomicmedlab/.local/share/wags_tails/mondo/mondo_v2023-09-12.owl'), 'v2023-09-12'
+Downloading mondo.obo: 100%|█████████████████| 171M/171M [00:28<00:00, 6.23MB/s]
+PosixPath('/Users/genomicmedlab/.local/share/wags_tails/mondo/mondo_v2023-09-12.obo'), 'v2023-09-12'
 ```
 
 Initialize the source class with the `silent` parameter set to True to suppress console output:
@@ -32,41 +54,14 @@ Initialize the source class with the `silent` parameter set to True to suppress
 >>> latest_file, version = m.get_latest(force_refresh=True)
 ```
 
+---
+
 ## Configuration
 
 All data is stored within source-specific subdirectories of a designated WagsTails data directory. By default, this location is `~/.local/share/wags_tails/`, but it can be configured by passing a Path directly to a data class on initialization, via the `$WAGS_TAILS_DIR` environment variable, or via [XDG data environment variables](https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.6.html).
 
-## Development
-
-Check out the repository:
-
-```shell
-git clone https://github.com/GenomicMedLab/wags-tails
-cd wags-tails
-```
-
-Create a developer environment, e.g. with `virtualenv`:
+---
 
-```shell
-python3 -m virtualenv venv
-source venv/bin/activate
-```
-
-Install dev and test dependencies, including `pre-commit`:
-
-```shell
-python3 -m pip install -e '.[dev,test]'
-pre-commit install
-```
-
-Check style:
+## Feedback and contributing
 
-```shell
-black . && ruff check --fix .
-```
-
-Run tests:
-
-```shell
-pytest
-```
+We welcome bug reports, feature requests, and code contributions from users and interested collaborators. The [documentation](https://wags-tails.readthedocs.io/latest/contributing.html) contains guidance for submitting feedback and contributing new code.

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    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/module_summary.rst

@@ -0,0 +1,7 @@
+{{ fullname | underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :exclude-members: model_fields, model_config

docs/source/_templates/module_summary_inh.rst

@@ -0,0 +1,8 @@
+{{ fullname | underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :inherited-members:
+   :exclude-members: model_fields, model_config, count, index

docs/source/_templates/module_summary_private.rst

@@ -0,0 +1,8 @@
+{{ fullname | underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :private-members:
+   :exclude-members: model_fields, model_config, _abc_impl

docs/source/changelog.rst

@@ -0,0 +1,7 @@
+Changelog
+---------
+
+.. changelog::
+    :changelog-url: https://wags-tails.readthedocs.io/en/stable/#changelog
+    :github: https://github.com/genomicmedlab/wags-tails/releases/
+    :pypi: https://pypi.org/project/wags-tails/

docs/source/conf.py

@@ -0,0 +1,80 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "wags-tails"
+copyright = "2023-2024, Wagner Lab"
+author = "Wagner Lab"
+html_title = "wags-tails"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "sphinx_github_changelog",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = []
+html_css_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+]
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/genomicmedlab/wags-tails",
+            "html": "",
+            "class": "fa-brands fa-solid fa-github",
+        },
+        {
+            "name": "Wagner Lab",
+            "url": "https://www.nationwidechildrens.org/specialties/institute-for-genomic-medicine/research-labs/wagner-lab",
+            "html": "",
+            "class": "fa-solid fa-house",
+        }
+    ],
+}
+# -- autodoc things ----------------------------------------------------------
+import os  # noqa: E402
+import sys  # noqa: E402
+
+sys.path.insert(0, os.path.abspath("../../src/"))
+autodoc_preserve_defaults = True
+autodoc_member_order = 'bysource'
+
+# -- get version -------------------------------------------------------------
+from importlib.metadata import version
+
+release = version = version("wags-tails")
+
+# -- linkcode ----------------------------------------------------------------
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+    filename = info["module"].replace(".", "/")
+    return f"https://github.com/genomicmedlab/wags-tails/blob/main/src/{filename}.py"
+
+
+# -- code block style --------------------------------------------------------
+pygments_style = "default"
+pygements_dark_style = "monokai"

docs/source/contributing.rst

@@ -0,0 +1,63 @@
+Contributing
+============
+
+Bug reports and feature requests
+--------------------------------
+
+Bugs and new feature requests can be submitted to the `issue tracker on GitHub <https://github.com/genomicmedlab/wags-tails/issues>`_. See `this StackOverflow post <https://stackoverflow.com/help/minimal-reproducible-example>`_ for tips on how to craft a helpful bug report.
+
+Adding new data sources
+-----------------------
+
+.. note::
+
+   ``wags-tails`` is intended to remain dependency-light to enable broad usage across our projects. If fetching new data requires adding additional dependencies, strong consideration should be given to whether it should be stood up as a :py:class:`CustomData <wags_tails.custom.CustomData>` subclass in the downstream library, instead of being added directly to ``wags-tails``.
+
+Generally, data classes for versioned data should inherit from :py:class:`~wags_tails.base_source.DataSource` and must, at minimum, implement two instance methods, :py:meth:`~wags_tails.base_source.DataSource._get_latest_version` and :py:meth:`~wags_tails.base_source.DataSource._download_data`, and two instance attributes, :py:attr:`~wags_tails.base_source.DataSource._src_name` and :py:attr:`~wags_tails.base_source.DataSource._filetype`. Data supplied via GitHub release should be implemented as a :py:class:`~wags_tails.base_source.GitHubDataSource` and also supply a :py:attr:`~wags_tails.base_source.GitHubDataSource._repo` attribute, but may not need to reimplement ``_get_latest_version()``. Unversioned data (i.e. a data object that is static or doesn't ever need to be updated) can be implemented as an :py:class:`~wags_tails.base_source.UnversionedDataSource`, which also obviates the need to define a ``_get_latest_version()`` method.
+
+Development setup
+-----------------
+
+Clone the repository: ::
+
+    git clone https://github.com/genomicmedlab/wags-tails
+    cd wags-tails
+
+Then initialize a virtual environment: ::
+
+    python3 -m virtualenv venv
+    source venv/bin/activate
+    python3 -m pip install -e '.[dev,tests,docs]'
+
+We use `pre-commit <https://pre-commit.com/#usage>`_ to run conformance tests before commits. This provides checks for:
+
+* Code format and style
+* Added large files
+* AWS credentials
+* Private keys
+
+Before your first commit, run: ::
+
+    pre-commit install
+
+Style
+-----
+
+Code style is managed by `Ruff <https://github.com/astral-sh/ruff>`_, and should be checked via pre-commit hook before commits. Final QC is applied with GitHub Actions to every pull request.
+
+Tests
+-----
+
+Tests are executed with `pytest <https://docs.pytest.org/en/7.1.x/getting-started.html>`_: ::
+
+    pytest
+
+Documentation
+-------------
+
+The documentation is built with Sphinx, which is included as part of the ``docs`` dependency group. Navigate to the `docs/` subdirectory and use `make` to build the HTML version: ::
+
+    cd docs
+    make html
+
+See the `Sphinx documentation <https://www.sphinx-doc.org/en/master/>`_ for more information.