docs: initial mkdocs conversion

Author: kenibrewer

.readthedocs.yml

@@ -4,21 +4,27 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-  jobs:
-    post_checkout:
-      # Full history is required for dunamai to calculate the version
-      - git fetch --unshallow || true
-    post_create_environment:
-      # Install poetry
-      # https://python-poetry.org/docs/#installing-manually
-      - pip install poetry
-      # Tell poetry to not use a virtual environment
-      - poetry config virtualenvs.create false
-    post_install:
-      # Install dependencies with 'docs' dependency group
-      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
-      - poetry install --with dev,docs --all-extras
+  commands:
+    # Full history is required for dunamai to calculate the version
+    - git fetch --unshallow || true
+    # Install poetry
+    # https://python-poetry.org/docs/#installing-manually
+    - pip install poetry
+    # Install poetry-dynamic-versioning plugin
+    - poetry self add "poetry-dynamic-versioning[plugin]"
+    # Build the project
+    - poetry build --format sdist
+    # Extract the built sdist
+    - mkdir -p dist/sdist && tar -xzf dist/*.tar.gz -C dist/sdist/
+    # Replace the files from the repo with the built sdist
+    - mv dist/sdist/*/pyproject.toml .
+    # Tell poetry to not use a virtual environment
+    - poetry config virtualenvs.create false
+    # Install dependencies with 'docs' dependency group
+    # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+    - poetry install --with dev,docs --all-extras
+    # Build the docs
+    - poetry run mkdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html --config-file mkdocs.yml
 
-sphinx:
-  builder: html
-  configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml

Makefile

@@ -18,8 +18,8 @@ test: ## Test the code with pytest
 
 .PHONY: docs
 docs: ## Build the documentation
-	@echo "📚 Building documentation"
-	@poetry run sphinx-build docs build
+	@echo "📚 Serving documentation"
+	@mkdocs serve
 
 .PHONY: build
 build: clean-build ## Build wheel file using poetry

README.md

@@ -1,5 +1,17 @@
 <img height="200" src="https://raw.githubusercontent.com/cytomining/pycytominer/main/logo/with-text-for-light-bg.png?raw=true">
 
+- [Data processing for image-based profiling](#data-processing-for-image-based-profiling)
+  - [Installation](##installation)
+  - [Frameworks](#frameworks)
+  - [API](#api)
+  - [Usage](#usage)
+    - [Pipeline orchestration](#pipeline-orchestration)
+  - [Other functionality](#other-functionality)
+    - [CellProfiler CSV collation](#cellprofiler-csv-collation)
+    - [Creating a cell locations lookup table](#creating-a-cell-locations-lookup-table)
+    - [Generating a GCT file for morpheus](#generating-a-gct-file-for-morpheus)
+  - [Citing pycytominer](#citing-pycytominer)
+
 # Data processing for image-based profiling
 
 [![Build Status](https://github.com/cytomining/pycytominer/actions/workflows/integration-test.yml/badge.svg?branch=main)](https://github.com/cytomining/pycytominer/actions/workflows/integration-test.yml?query=branch%3Amain)
@@ -111,19 +123,7 @@ And, more specifically than that, image-based profiling readouts from [CellProfi
 
 Therefore, we have included some custom tools in `pycytominer/cyto_utils` that provides other functionality:
 
-- [Data processing for image-based profiling](#data-processing-for-image-based-profiling)
-  - [Installation](#installation)
-  - [Frameworks](#frameworks)
-  - [API](#api)
-  - [Usage](#usage)
-    - [Pipeline orchestration](#pipeline-orchestration)
-  - [Other functionality](#other-functionality)
-    - [CellProfiler CSV collation](#cellprofiler-csv-collation)
-    - [Creating a cell locations lookup table](#creating-a-cell-locations-lookup-table)
-    - [Generating a GCT file for morpheus](#generating-a-gct-file-for-morpheus)
-  - [Citing pycytominer](#citing-pycytominer)
-
-Note, [`pycytominer.cyto_utils.cells.SingleCells()`](pycytominer/cyto_utils/cells.py) contains code to interact with single-cell SQLite files, which are output from CellProfiler.
+Note, [`pycytominer.cyto_utils.cells.SingleCells()`](./pycytominer/cyto_utils/cells.py) contains code to interact with single-cell SQLite files, which are output from CellProfiler.
 Processing capabilities for SQLite files depends on SQLite file size and your available computational resources (for ex. memory and cores).
 
 ### CellProfiler CSV collation

docs/cyto_utils.md

@@ -0,0 +1,5 @@
+# Cyto utilities
+
+Functions enabling smooth interaction with CellProfiler and DeepProfiler output formats.
+
+::: pycytominer.cyto_utils

docs/functions.md

@@ -0,0 +1,16 @@
+# Main Functions
+
+<!-- prettier-ignore-start -->
+<!-- mkdocs block -->
+
+::: pycytominer
+    options:
+      members: 
+        - aggregate
+        - annotate
+        - consensus
+        - feature_select
+        - normalize
+
+<!-- mkdocs block END -->
+<!-- prettier-ignore-end -->

docs/index.md

@@ -0,0 +1,3 @@
+{%
+   include-markdown "../README.md"
+%}

docs/index.rst

@@ -1,14 +1,13 @@
-Install
-=======
+# Installation
 
 To install pycytominer, use pip:
 
-.. code-block:: bash
-
+```bash
    pip install pycytominer
+```
 
 You can also install pycytominer with conda:
 
-.. code-block:: bash
-
+```bash
    conda install -c conda-forge pycytominer
+```

docs/install.rst docs/install.md

@@ -0,0 +1,6 @@
+# Operations
+
+We do not recommend interacting with these functions directly.
+The core pycytominer API uses these operations internally.
+
+::: pycytominer.operations

docs/modules.rst

@@ -0,0 +1,13 @@
+# Tutorials
+
+`This <https://github.com/cytomining/pipeline-examples#readme>`\_ tutorial shows how to run a image-based profiling pipeline using pycytominer. Using IPython notebooks, it walks through the following steps:
+
+#. Downloading a dataset of single cell `CellProfiler <https://cellprofiler.org/>`_ profiles.
+#. Processing the profiles using PyCytominer. This includes the following steps:
+#. Data initialization
+#. Single cell aggregation to create well-level profiles
+#. Addition of experiment metadata to the well-level profiles
+#. Profile normalization
+#. Feature selection
+#. Forming consensus signatures
+#. Evaluating the profile quality using `cytominer-eval <https://github.com/cytomining/cytominer-eval>`_.

docs/operations.md

@@ -0,0 +1,6 @@
+# Walkthroughs
+
+.. toctree::
+:maxdepth: 1
+
+walkthroughs/single_cell_usage.ipynb