docs: Sync with tutorial (#43)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Version 0.4.2 - 0.4.7
+
+- Fix issue coercing `SummarizedExperiments` to `AnnData` objects and vice-versa.
+- Handling coercions when matrices are delayed arrays or backed (for `AnnData`).
+- Update sphinx configuration to run snippets in the documentation.
+
 ## Version 0.4.0 to 0.4.1
 
 This is a complete rewrite of the package, following the functional paradigm from our [developer notes](https://github.com/BiocPy/developer_guide#use-functional-discipline).

README.md

@@ -4,20 +4,26 @@
 
 # SingleCellExperiment
 
-Container class to represent single-cell experiments; follows Bioconductor's [SingleCellExperiment](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html).
+This package provides container class to represent single-cell experimental data as 2-dimensional matrices. In these matrices, the rows typically denote features or genomic regions of interest, while columns represent cells. In addition, a `SingleCellExperiment` (SCE) object may contain low-dimensionality embeddings, alternative experiments performed on same sample or set of cells. Follows Bioconductor's [SingleCellExperiment](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html).
 
 
 ## Install
 
-Package is published to [PyPI](https://pypi.org/project/singlecellexperiment/)
+To get started, install the package from [PyPI](https://pypi.org/project/singlecellexperiment/)
 
-```shell
+```bash
 pip install singlecellexperiment
 ```
 
 ## Usage
 
-Readers are available to read AnnData, H5AD or 10x (MTX, H5) V3 formats as `SingleCellExperiment` objects.
+The `SingleCellExperiment` extends [RangeSummarizedExperiment](https://github.com/BiocPy/SummarizedExperiment) and contains additional attributes:
+
+- `reduced_dims`: Slot for low-dimensionality embeddings for each cell.
+- `alternative_experiments`: Manages multi-modal experiments performed on the same sample or set of cells.
+- `row_pairs` or `column_pairs`: Stores relationships between features or cells.
+
+Readers are available to parse h5ad or `AnnData` objects to SCE:
 
 ```python
 import singlecellexperiment
@@ -51,7 +57,8 @@ tse = SingleCellExperiment(
 )
 ```
 
-Since `SingleCellExperiment` extends `SummarizedExperiment`, most methods especially slicing and accessors are applicable here. Checkout the [documentation](https://biocpy.github.io/SingleCellExperiment/) for more info.
+Since `SingleCellExperiment` extends `RangeSummarizedExperiment`, most methods especially slicing and accessors are applicable here.
+Checkout the [documentation](https://biocpy.github.io/SingleCellExperiment/) for more info.
 
 <!-- pyscaffold-notes -->
 

docs/conf.py

@@ -72,14 +72,16 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 
 # Enable markdown
-extensions.append("myst_parser")
+# extensions.append("myst_parser")
+extensions.append("myst_nb")
 
 # Configure MyST-Parser
 myst_enable_extensions = [
@@ -167,9 +169,11 @@
 todo_emit_warnings = True
 
 autodoc_default_options = {
-    'special-members': True,
-    'undoc-members': False,
-    'exclude-members': '__weakref__, __dict__, __str__, __module__, __init__'
+    # 'members': 'var1, var2',
+    # 'member-order': 'bysource',
+    "special-members": True,
+    "undoc-members": True,
+    "exclude-members": "__weakref__, __dict__, __str__, __module__",
 }
 
 autosummary_generate = True
@@ -309,7 +313,8 @@
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
     "biocframe": ("https://biocpy.github.io/BiocFrame", None),
     "genomicranges": ("https://biocpy.github.io/GenomicRanges", None),
-    "singlecellexperiment": ("https://biocpy.github.io/SingleCellExperiment", None),
+    "summarizedexperiment": ("https://biocpy.github.io/SummarizedExperiment", None),
+    "biocutils": ("https://biocpy.github.io/BiocUtils", None),
 }
 
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/index.md

@@ -1,22 +1,22 @@
 # SingleCellExperiment
 
-Container class for representing data from single-cell experiments; follows Bioconductor's [SingleCellExperiment](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html).
+This package provides container class to represent single-cell experimental data as 2-dimensional matrices. In these matrices, the rows typically denote features or genomic regions of interest, while columns represent cells. In addition, a `SingleCellExperiment` (SCE) object may contain low-dimensionality embeddings, alternative experiments performed on same sample or set of cells. Follows Bioconductor's [SingleCellExperiment](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html).
 
 
 ## Install
 
-Package is published to [PyPI](https://pypi.org/project/singlecellexperiment/)
+To get started, install the package from [PyPI](https://pypi.org/project/singlecellexperiment/)
 
-```shell
+```bash
 pip install singlecellexperiment
 ```
+
 ## Contents
 
 ```{toctree}
 :maxdepth: 2
 
-Overview <readme>
-Tutorial <tutorial>
+Overview <tutorial>
 Module Reference <api/modules>
 Contributions & Help <contributing>
 License <license>

docs/requirements.txt

@@ -1,7 +1,9 @@
 furo
+myst-nb
 # Requirements file for ReadTheDocs, check .readthedocs.yml.
 # To build the module reference correctly, make sure every external package
 # under `install_requires` in `setup.cfg` is also listed here!
 # sphinx_rtd_theme
 myst-parser[linkify]
 sphinx>=3.2.1
+sphinx-autodoc-typehints