Switch from using rubric in release notes (scverse#3172)

AminAlam · Jul 26, 2024 · b78e9dc · b78e9dc
1 parent 62454de
commit b78e9dc
Show file tree

Hide file tree

Showing 53 changed files with 174 additions and 216 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -2,10 +2,12 @@
 
 import sys
 from datetime import datetime
+from functools import partial
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import matplotlib  # noqa
+from docutils import nodes
 from packaging.version import Version
 
 # Don’t use tkinter agg when importing scanpy → … → matplotlib
@@ -50,7 +52,14 @@
 templates_path = ["_templates"]
 master_doc = "index"
 default_role = "literal"
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "**.ipynb_checkpoints",
+    # exclude all 0.x.y.md files, but not index.md
+    "release-notes/[!i]*.md",
+]
 
 extensions = [
     "myst_nb",
@@ -96,6 +105,7 @@
     "html_admonition",
 ]
 myst_url_schemes = ("http", "https", "mailto", "ftp")
+myst_heading_anchors = 3
 nb_output_stderr = "remove"
 nb_execution_mode = "off"
 nb_merge_streams = True
@@ -151,6 +161,8 @@
 
 def setup(app: Sphinx):
     """App setup hook."""
+    app.add_generic_role("small", partial(nodes.inline, classes=["small"]))
+    app.add_generic_role("smaller", partial(nodes.inline, classes=["smaller"]))
     app.add_config_value(
         "recommonmark_config",
         {

diff --git a/docs/ecosystem.md b/docs/ecosystem.md
@@ -1,13 +1,5 @@
 # Ecosystem
 
-```{eval-rst}
-.. role:: small
-```
-
-```{eval-rst}
-.. role:: smaller
-```
-
 ```{warning}
 We are no longer accepting new tools on this page.
 Instead, please submit your tool to the [scverse ecosystem package listing](https://scverse.org/packages/#ecosystem).

diff --git a/docs/index.md b/docs/index.md
@@ -2,14 +2,6 @@
 :end-before: '## Citation'
 ```
 
-```{eval-rst}
-.. role:: small
-```
-
-```{eval-rst}
-.. role:: smaller
-```
-
 ::::{grid} 1 2 3 3
 :gutter: 2
 

diff --git a/docs/news.md b/docs/news.md
@@ -1,12 +1,6 @@
 (News)=
-
 ## News
 
-```{eval-rst}
-.. role:: small
-
-```
-
 <!-- marker: after prelude -->
 
 ### `rapids-singlecell` brings scanpy to the GPU! {small}`2024-03-18`

diff --git a/docs/release-notes/0.1.0.md b/docs/release-notes/0.1.0.md
@@ -1,3 +1,4 @@
+(v0.1.0)=
 ### 0.1.0 {small}`2017-05-17`
 
 Scanpy computationally outperforms and allows reproducing both the [Cell Ranger

diff --git a/docs/release-notes/0.2.1.md b/docs/release-notes/0.2.1.md
@@ -1,3 +1,4 @@
+(v0.2.1)=
 ### 0.2.1 {small}`2017-07-24`
 
 Scanpy includes preprocessing, visualization, clustering, pseudotime and

diff --git a/docs/release-notes/0.2.9.md b/docs/release-notes/0.2.9.md
@@ -1,7 +1,7 @@
+(v0.2.9)=
 ### 0.2.9 {small}`2017-10-25`
 
-```{rubric} Initial release of the new trajectory inference method [PAGA](https://github.com/theislab/paga)
-```
+#### Initial release of the new trajectory inference method [PAGA](https://github.com/theislab/paga)
 
 - {func}`~scanpy.tl.paga` computes an abstracted, coarse-grained (PAGA) graph of the neighborhood graph {smaller}`A Wolf`
 - {func}`~scanpy.pl.paga_compare` plot this graph next an embedding {smaller}`A Wolf`

diff --git a/docs/release-notes/0.3.0.md b/docs/release-notes/0.3.0.md
@@ -1,3 +1,4 @@
+(v0.3.0)=
 ### 0.3.0 {small}`2017-11-16`
 
 - {class}`~anndata.AnnData` gains method {meth}`~anndata.AnnData.concatenate` {smaller}`A Wolf`

diff --git a/docs/release-notes/0.3.2.md b/docs/release-notes/0.3.2.md
@@ -1,3 +1,4 @@
+(v0.3.2)=
 ### 0.3.2 {small}`2017-11-29`
 
 - finding marker genes via {func}`~scanpy.pl.rank_genes_groups_violin` improved,

diff --git a/docs/release-notes/0.4.0.md b/docs/release-notes/0.4.0.md
@@ -1,3 +1,4 @@
+(v0.4.0)=
 ### 0.4.0 {small}`2017-12-23`
 
 - export to [SPRING] {cite:p}`Weinreb2017` for interactive visualization of data:

diff --git a/docs/release-notes/0.4.2.md b/docs/release-notes/0.4.2.md
@@ -1,3 +1,4 @@
+(v0.4.2)=
 ### 0.4.2 {small}`2018-01-07`
 
 - amendments in [PAGA](https://github.com/theislab/paga) and its plotting functions {smaller}`A Wolf`
diff --git a/docs/release-notes/0.4.3.md b/docs/release-notes/0.4.3.md
@@ -1,3 +1,4 @@
+(v0.4.3)=
 ### 0.4.3 {small}`2018-02-09`
 
 - {func}`~scanpy.pl.clustermap`: heatmap from hierarchical clustering,

diff --git a/docs/release-notes/0.4.4.md b/docs/release-notes/0.4.4.md
@@ -0,0 +1,6 @@
+(v0.4.4)=
+### 0.4.4 {small}`2018-02-26`
+
+- embed cells using {func}`~scanpy.tl.umap` {cite:p}`McInnes2018` {pr}`92` {smaller}`G Eraslan`
+- score sets of genes, e.g. for cell cycle, using {func}`~scanpy.tl.score_genes` {cite:p}`Satija2015`:
+  [notebook](https://nbviewer.jupyter.org/github/theislab/scanpy_usage/blob/master/180209_cell_cycle/cell_cycle.ipynb)
diff --git a/docs/release-notes/1.0.0.md b/docs/release-notes/1.0.0.md
@@ -1,7 +1,7 @@
+(v1.0.0)=
 ### 1.0.0 {small}`2018-03-30`
 
-```{rubric} Major updates
-```
+#### Major updates
 
 - Scanpy is much faster and more memory efficient: preprocess, cluster and
   visualize 1.3M cells in [6h], 130K cells in [14min], and 68K cells in [3min] {smaller}`A Wolf`
@@ -10,8 +10,7 @@
   delegated {smaller}`A Wolf`
 
 ```{warning}
-```{rubric} Upgrading to 1.0 isn’t fully backwards compatible in the following changes
-```
+#### Upgrading to 1.0 isn’t fully backwards compatible in the following changes
 
 - the graph-based tools {func}`~scanpy.tl.louvain`
   {func}`~scanpy.tl.dpt` {func}`~scanpy.tl.draw_graph`
@@ -35,8 +34,7 @@
   some results might therefore look slightly different
 ```
 
-```{rubric} Further updates
-```
+#### Further updates
 
 - UMAP {cite:p}`McInnes2018` can serve as a first visualization of the data just as tSNE,
   in contrast to tSNE, UMAP directly embeds the single-cell graph and is faster;

diff --git a/docs/release-notes/1.1.0.md b/docs/release-notes/1.1.0.md
@@ -1,3 +1,4 @@
+(v1.1.0)=
 ### 1.1.0 {small}`2018-06-01`
 
 - {func}`~scanpy.set_figure_params` by default passes `vector_friendly=True` and allows you to produce reasonablly sized pdfs by rasterizing large scatter plots {smaller}`A Wolf`

diff --git a/docs/release-notes/1.10.0.md b/docs/release-notes/1.10.0.md
@@ -1,3 +1,4 @@
+(v1.10.0)=
 ### 1.10.0 {small}`2024-03-26`
 
 `scanpy` 1.10 brings a large amount of new features, performance improvements, and improved documentation.
@@ -10,8 +11,7 @@ Some highlights:
 * Ability to `mask` observations or variables from a number of methods (see {doc}`/tutorials/plotting/advanced` for an example with plotting embeddings)
 * A new function {func}`~scanpy.get.aggregate` for computing aggregations of your data, very useful for pseudo bulking!
 
-```{rubric} Features
-```
+#### Features
 
 * {func}`~scanpy.pp.scrublet` and {func}`~scanpy.pp.scrublet_simulate_doublets` were moved from {mod}`scanpy.external.pp` to {mod}`scanpy.pp`. The `scrublet` implementation is now maintained as part of scanpy {pr}`2703` {smaller}`P Angerer`
 * {func}`scanpy.pp.pca`, {func}`scanpy.pp.scale`, {func}`scanpy.pl.embedding`, and {func}`scanpy.experimental.pp.normalize_pearson_residuals_pca` now support a `mask` parameter {pr}`2272` {smaller}`C Bright, T Marcella, & P Angerer`
@@ -32,8 +32,7 @@ Some highlights:
 * {func}`scanpy.pp.scale` now clips `np.ndarray` also at `- max_value` for zero-centering {pr}`2913` {smaller}`S Dicks`
 * Support sparse chunks in dask {func}`~scanpy.pp.scale`, {func}`~scanpy.pp.normalize_total` and {func}`~scanpy.pp.highly_variable_genes` (`seurat` and `cell-ranger` tested) {pr}`2856` {smaller}`ilan-gold`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Doc style overhaul {pr}`2220` {smaller}`A Gayoso`
 * Re-add search-as-you-type, this time via `readthedocs-sphinx-search` {pr}`2805` {smaller}`P Angerer`
@@ -44,8 +43,7 @@ Some highlights:
 * Overhauled {doc}`/tutorials/index` page, and added new {doc}`/how-to/index` section to docs {pr}`2901` {smaller}`I Virshup`
 * Added a new tutorial on working with dask ({doc}`/tutorials/experimental/dask`) {pr}`2901` {smaller}`I Gold` {smaller}`I Virshup`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Updated {func}`~scanpy.read_visium` such that it can read spaceranger 2.0 files {smaller}`L Lehner`
 * Fix {func}`~scanpy.pp.normalize_total` for dask {pr}`2466` {smaller}`P Angerer`
@@ -61,14 +59,12 @@ Some highlights:
 * Fix pytest deprecation warning {pr}`2879` {smaller}`P Angerer`
 
 
-```{rubric} Development
-```
+#### Development
 
 * Scanpy is now tested against python 3.12 {pr}`2863` {smaller}`ivirshup`
 * Fix testing package build {pr}`2468` {smaller}`P Angerer`
 
-```{rubric} Deprecations
-```
+#### Deprecations
 
 * Dropped support for Python 3.8. [More details here](https://numpy.org/neps/nep-0029-deprecation_policy.html). {pr}`2695` {smaller}`P Angerer`
 * Deprecated specifying large numbers of function parameters by position as opposed to by name/keyword in all public APIs.

diff --git a/docs/release-notes/1.10.1.md b/docs/release-notes/1.10.1.md
@@ -1,16 +1,14 @@
+(v1.10.1)=
 ### 1.10.1 {small}`2024-04-09`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Added {doc}`how-to example </how-to/plotting-with-marsilea>` on plotting with [Marsilea](https://marsilea.readthedocs.io) {pr}`2974` {smaller}`Y Zheng`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Fix `aggregate` when aggregating by more than two groups {pr}`2965` {smaller}`I Virshup`
 
 
-```{rubric} Performance
-```
+#### Performance
 * {func}`~scanpy.pp.scale` now uses numba kernels for `sparse.csr_matrix` and `sparse.csc_matrix` when `zero_center==False` and `mask_obs` is provided. This greatly speed up execution {pr}`2942` {smaller}`S Dicks`
diff --git a/docs/release-notes/1.10.2.md b/docs/release-notes/1.10.2.md
@@ -1,21 +1,19 @@
+(v1.10.2)=
 ### 1.10.2 {small}`2024-06-25`
 
-```{rubric} Development features
-```
+#### Development features
 
 * Add performance benchmarking {pr}`2977` {smaller}`R Shrestha`, {smaller}`P Angerer`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Document several missing parameters in docstring {pr}`2888` {smaller}`S Cheney`
 * Fixed incorrect instructions in "testing" dev docs {pr}`2994` {smaller}`I Virshup`
 * Update marsilea tutorial to use `group_` methods {pr}`3001` {smaller}`I Virshup`
 * Fixed citations {pr}`3032` {smaller}`P Angerer`
 * Improve dataset documentation {pr}`3060` {smaller}`P Angerer`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Compatibility with `matplotlib` 3.9 {pr}`2999` {smaller}`I Virshup`
 * Add clear errors where `backed` mode-like matrices (i.e., from `sparse_dataset`) are not supported {pr}`3048` {smaller}`I gold`
@@ -24,8 +22,7 @@
 * Fix zappy support {pr}`3089` {smaller}`P Angerer`
 * Fix dotplot group order with {mod}`pandas` 1.x {pr}`3101` {smaller}`P Angerer`
 
-```{rubric} Performance
-```
+#### Performance
 
 * `sparse_mean_variance_axis` now uses all cores for the calculations {pr}`3015` {smaller}`S Dicks`
 * `pp.highly_variable_genes` with `flavor=seurat_v3` now uses a numba kernel {pr}`3017` {smaller}`S Dicks`

diff --git a/docs/release-notes/1.10.3.md b/docs/release-notes/1.10.3.md
@@ -1,18 +1,15 @@
+(v1.10.3)=
 ### 1.10.3 {small}`the future`
 
-```{rubric} Development features
-```
+#### Development features
 
-```{rubric} Docs
-```
+#### Docs
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Prevent empty control gene set in {func}`~scanpy.tl.score_genes` {pr}`2875` {smaller}`M Müller`
 * Fix `subset=True` of {func}`~scanpy.pp.highly_variable_genes` when `flavor` is `seurat` or `cell_ranger`, and `batch_key!=None` {pr}`3042` {smaller}`E Roellin`
 * Add compatibility with {mod}`numpy` 2.0 {pr}`3065` and {pr}`3115` {smaller}`P Angerer`
 * Fix `legend_loc` argument in {func}`scanpy.pl.embedding` not accepting matplotlib parameters {pr}`3163` {smaller}`P Angerer`
 
-```{rubric} Performance
-```
+#### Performance
diff --git a/docs/release-notes/1.11.0.md b/docs/release-notes/1.11.0.md
@@ -1,16 +1,13 @@
+(v1.11.0)=
 ### 1.11.0 {small}`the future`
 
-```{rubric} Features
-```
+#### Features
 
 * Add layer argument to {func}`scanpy.tl.score_genes` and {func}`scanpy.tl.score_genes_cell_cycle` {pr}`2921` {smaller}`L Zappia`
 * Prevent `raw` conflict with `layer` in {func}`~scanpy.tl.score_genes` {pr}`3155` {smaller}`S Dicks`
 
-```{rubric} Docs
-```
+#### Docs
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
-```{rubric} Deprecations
-```
+#### Deprecations
diff --git a/docs/release-notes/1.2.0.md b/docs/release-notes/1.2.0.md
@@ -1,3 +1,4 @@
+(v1.2.0)=
 ### 1.2.0 {small}`2018-06-08`
 
 - {func}`~scanpy.tl.paga` improved, see [PAGA](https://github.com/theislab/paga); the default model changed, restore the previous default model by passing `model='v1.0'`
diff --git a/docs/release-notes/1.2.1.md b/docs/release-notes/1.2.1.md
@@ -1,6 +1,6 @@
+(v1.2.1)=
 ### 1.2.1 {small}`2018-06-08`
 
-~~~{rubric} Plotting of {ref}`pl-generic` marker genes and quality control.
-~~~
+#### Plotting of {ref}`pl-generic` marker genes and quality control.
 
 - {func}`~scanpy.pl.highest_expr_genes` for quality control; plot genes with highest mean fraction of cells, similar to `plotQC` of *Scater* {cite:p}`McCarthy2017` {pr}`169` {smaller}`F Ramirez`
diff --git a/docs/release-notes/1.3.1.md b/docs/release-notes/1.3.1.md
@@ -1,20 +1,18 @@
+(v1.3.1)=
 ### 1.3.1 {small}`2018-09-03`
 
-```{rubric} RNA velocity in single cells {cite:p}`LaManno2018`
-```
+#### RNA velocity in single cells {cite:p}`LaManno2018`
 
 - Scanpy and AnnData support loom’s layers so that computations for single-cell RNA velocity {cite:p}`LaManno2018` become feasible {smaller}`S Rybakov and V Bergen`
 - [scvelo] harmonizes with Scanpy and is able to process loom files with splicing information produced by Velocyto {cite:p}`LaManno2018`, it runs a lot faster than the count matrix analysis of Velocyto and provides several conceptual developments
 
-~~~{rubric} Plotting ({ref}`pl-generic`)
-~~~
+#### Plotting ({ref}`pl-generic`)
 
 - {func}`~scanpy.pl.dotplot` for visualizing genes across conditions and clusters, see [here](https://gist.github.com/fidelram/2289b7a8d6da055fb058ac9a79ed485c) {pr}`199` {smaller}`F Ramirez`
 - {func}`~scanpy.pl.heatmap` for pretty heatmaps {pr}`175` {smaller}`F Ramirez`
 - {func}`~scanpy.pl.violin` produces very compact overview figures with many panels {pr}`175` {smaller}`F Ramirez`
 
-~~~{rubric} There now is a section on imputation in {doc}`external <../external/index>`:
-~~~
+#### There now is a section on imputation in {doc}`external <../external/index>`:
 
 - {func}`~scanpy.external.pp.magic` for imputation using data diffusion {cite:p}`vanDijk2018` {pr}`187` {smaller}`S Gigante`
 - {func}`~scanpy.external.pp.dca` for imputation and latent space construction using an autoencoder {cite:p}`Eraslan2019` {pr}`186` {smaller}`G Eraslan`

diff --git a/docs/release-notes/1.3.3.md b/docs/release-notes/1.3.3.md
@@ -1,18 +1,16 @@
+(v1.3.3)=
 ### 1.3.3 {small}`2018-11-05`
 
-```{rubric} Major updates
-```
+#### Major updates
 
 - a fully distributed preprocessing backend {smaller}`T White and the Laserson Lab`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.read_10x_h5` and {func}`~scanpy.read_10x_mtx` read Cell Ranger 3.0 outputs {pr}`334` {smaller}`Q Gong`
 
 ```{note}
-```{rubric} Also see changes in anndata 0.6.
-```
+#### Also see changes in anndata 0.6.
 
 - changed default compression to `None` in {meth}`~anndata.AnnData.write_h5ad` to speed up read and write, disk space use is usually less critical
 - performance gains in {meth}`~anndata.AnnData.write_h5ad` due to better handling of strings and categories {smaller}`S Rybakov`

diff --git a/docs/release-notes/1.3.4.md b/docs/release-notes/1.3.4.md
@@ -1,3 +1,4 @@
+(v1.3.4)=
 ### 1.3.4 {small}`2018-11-24`
 
 - {func}`~scanpy.tl.leiden` wraps the recent graph clustering package by {cite:t}`Traag2019` {smaller}`K Polanski`