cytomining · gwaybio · Jun 13, 2023 · Jun 10, 2023 · Jun 10, 2023 · Jun 10, 2023
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,7 +1,11 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 python:
-  version: 3.11
   install:
     - requirements: docs/requirements.txt
     - requirements: requirements.txt

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,6 +18,7 @@ If you are stuck, please feel free to ask any questions or ask for help.
 - [Suggesting enhancements](#suggesting-enhancements)
 - [Your first code contribution](#your-first-code-contribution)
 - [Pull requests](#pull-requests)
+- [Documentation](#documentation)
 - [Dev environments](#dev-environments)
 
 [Style guides](#style-guides)
@@ -106,6 +107,19 @@ We will do our best to review the code addition in a timely fashion.
 Ensuring that you follow all steps above will increase our speed and ability to review.
 We will check for accuracy, style, code coverage, and scope.
 
+### Documentation
+
+We use [sphinx](https://www.sphinx-doc.org/en/master/index.html) for autodocumentation of docstrings, using the [napoleon extenstion](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) to parse [NumPy style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html), implemented with a [furo](https://pradyunsg.me/furo/) theme.
+We host our documentation on [readthedocs.org](https://readthedocs.org/) at [https://pycytominer.readthedocs.io/en/latest/](https://pycytominer.readthedocs.io/en/latest/).
+
+To build and test changes to the docs locally, run the following command:
+
+```bash
+sphinx-build -b html docs build
+```
+
+See [`docs/conf.py`](docs/conf.py) for full documentation configuration.
+
 ### Dev environments
 
 #### Local devcontainer

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <img height="200" src="https://raw.githubusercontent.com/cytomining/pycytominer/master/logo/with-text-for-light-bg.png?raw=true">
 
-# Pycytominer: Data processing functions for image-based profiling
+# Data processing for image-based profiling
 
 [![Build Status](https://travis-ci.org/cytomining/pycytominer.svg?branch=master)](https://travis-ci.org/cytomining/pycytominer)
 [![Coverage Status](https://codecov.io/gh/cytomining/pycytominer/branch/master/graph/badge.svg)](https://codecov.io/github/cytomining/pycytominer?branch=master)
@@ -10,7 +10,8 @@
 Pycytominer is a suite of common functions used to process high dimensional readouts from high-throughput cell experiments.
 The tool is most often used for processing data through the following pipeline:
 
-![pipeline](/media/pipeline.png)
+<img height="500" src="https://github.com/cytomining/pycytominer/blob/master/media/pipeline.png?raw=true">
+[Click here for high resolution image](https://github.com/cytomining/pycytominer/blob/master/media/pipeline.png)
 
 Image data flow from a microscope to cell segmentation and feature extraction tools (e.g. CellProfiler or DeepProfiler).
 From here, additional single cell processing tools curate the single cell readouts into a form manageable for pycytominer input.

diff --git a/docs/conf.py b/docs/conf.py
@@ -12,6 +12,7 @@
 #
 import os
 import sys
+import pathlib
 from datetime import date
 
 sys.path.insert(0, os.path.abspath(".."))
@@ -35,7 +36,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_copybutton", "m2r2"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -50,9 +51,28 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+pycytominer_hex = "#88239A"
+# Furo theme options specified here: https://pradyunsg.me/furo/
+html_theme = "furo"
+# Furo theme option colors specified here:
+# https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/variables/_colors.scss
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": pycytominer_hex,
+        "color-brand-content": pycytominer_hex,
+        "color-api-pre-name": pycytominer_hex,
+        "color-api-name": pycytominer_hex,
+    },
+    "dark_css_variables": {
+        "color-brand-primary": pycytominer_hex,
+        "color-brand-content": pycytominer_hex,
+        "color-api-pre-name": pycytominer_hex,
+        "color-api-name": pycytominer_hex,
+    },
+}
 
 # 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 = ["_static"]
+# html_static_path = ["_static"]
+html_logo = "../logo/just-icon-150px.svg"
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,10 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Pycytominer
-===========
-
-Software for processing image-based profiling readouts.
+.. mdinclude:: ../README.md
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/pycytominer.cyto_utils.rst b/docs/pycytominer.cyto_utils.rst
@@ -1,8 +1,7 @@
-pycytominer.cyto\_utils package
-===============================
+Cyto utilities
+==============
 
-Submodules
-----------
+Functions enabling smooth interaction with CellProfiler and DeepProfiler output formats.
 
 pycytominer.cyto\_utils.cells module
 ------------------------------------

diff --git a/docs/pycytominer.operations.rst b/docs/pycytominer.operations.rst
@@ -1,8 +1,8 @@
-pycytominer.operations package
-==============================
+Operations
+==========
 
-Submodules
-----------
+We do not recommend interacting with these functions directly.
+The core pycytominer API uses these operations internally.
 
 pycytominer.operations.correlation\_threshold module
 ----------------------------------------------------
@@ -20,14 +20,6 @@ pycytominer.operations.get\_na\_columns module
    :undoc-members:
    :show-inheritance:
 
-pycytominer.operations.sparse\_random\_projection module
---------------------------------------------------------
-
-.. automodule:: pycytominer.operations.sparse_random_projection
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 pycytominer.operations.transform module
 ---------------------------------------
 

diff --git a/docs/pycytominer.rst b/docs/pycytominer.rst
@@ -1,18 +1,5 @@
-pycytominer package
-===================
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 4
-
-   pycytominer.cyto_utils
-   pycytominer.operations
-   pycytominer.tests
-
-Submodules
-----------
+Core functions
+==============
 
 pycytominer.aggregate module
 ----------------------------
@@ -30,10 +17,10 @@ pycytominer.annotate module
    :undoc-members:
    :show-inheritance:
 
-pycytominer.consensus module
+pycytominer.normalize module
 ----------------------------
 
-.. automodule:: pycytominer.consensus
+.. automodule:: pycytominer.normalize
    :members:
    :undoc-members:
    :show-inheritance:
@@ -46,14 +33,23 @@ pycytominer.feature\_select module
    :undoc-members:
    :show-inheritance:
 
-pycytominer.normalize module
+pycytominer.consensus module
 ----------------------------
 
-.. automodule:: pycytominer.normalize
+.. automodule:: pycytominer.consensus
    :members:
    :undoc-members:
    :show-inheritance:
 
+Helper functions
+----------------
+
+.. toctree::
+   :maxdepth: 4
+
+   pycytominer.cyto_utils
+   pycytominer.operations
+
 Module contents
 ---------------
 

diff --git a/docs/pycytominer.tests.rst b/docs/pycytominer.tests.rst