Backport PR #1346: Switch from using rubric in release notes (#1551)

Co-authored-by: Isaac Virshup <[email protected]>
scverse · Jul 1, 2024 · 474250d · 474250d
1 parent 6f26e9a
commit 474250d
Show file tree

Hide file tree

Showing 32 changed files with 161 additions and 208 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -2,10 +2,13 @@
 
 import sys
 from datetime import datetime
+from functools import partial
 from importlib import metadata
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from docutils import nodes
+
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
@@ -33,6 +36,8 @@
     ".DS_Store",
     "**.ipynb_checkpoints",
     "tutorials/notebooks/*.rst",
+    # exclude all 0.x.y.md files, but not index.md
+    "release-notes/[!i]*.md",
 ]
 pygments_style = "sphinx"
 
@@ -59,6 +64,7 @@
 myst_enable_extensions = [
     "html_image",  # So README.md can be used on github and sphinx docs
 ]
+myst_heading_anchors = 3
 
 # Generate the API documentation when building
 autosummary_generate = True
@@ -96,8 +102,8 @@
 
 
 def setup(app: Sphinx):
-    # Don’t allow broken links. DO NOT CHANGE THIS LINE, fix problems instead.
-    app.warningiserror = True
+    app.add_generic_role("small", partial(nodes.inline, classes=["small"]))
+    app.add_generic_role("smaller", partial(nodes.inline, classes=["smaller"]))
 
 
 intersphinx_mapping = dict(

diff --git a/docs/index.md b/docs/index.md
@@ -1,20 +1,10 @@
-```{eval-rst}
-.. role:: small
-```
-
-```{eval-rst}
-.. role:: smaller
-```
-
 ```{include} ../README.md
 ```
 
 # Latest additions
 
-```{include} release-notes/release-latest.md
-```
-
-See {doc}`/release-notes/index` for more.
+See {doc}`/release-notes/index`,
+particularly {ref}`v0.10` for the current release.
 
 ```{toctree}
 :hidden: true

diff --git a/docs/news.md b/docs/news.md
@@ -1,7 +1,3 @@
-```{eval-rst}
-.. role:: small
-```
-
 # Muon paper published {small}`2022-02-02`
 
 Muon has been published in Genome Biology [^cite_bredikhin22].

diff --git a/docs/release-notes/0.10.0.md b/docs/release-notes/0.10.0.md
@@ -1,7 +1,7 @@
+(v0.10.0)=
 ### 0.10.0 {small}`2023-10-06`
 
-```{rubric} Features
-```
+#### Features
 
 **GPU Support**
 
@@ -23,28 +23,23 @@
 * `AnnDataReadError`s have been removed. The original error is now thrown with additional information in a note {pr}`1055` {user}`ivirshup`
 
 
-```{rubric} Documentation
-```
+#### Documentation
 
 * Added zarr examples to {doc}`file format docs</fileformat-prose>` {pr}`1162` {user}`ivirshup`
 
-```{rubric} Breaking changes
-```
+#### Breaking changes
 
 * {meth}`anndata.AnnData.transpose` no longer copies unnecessarily. If you rely on the copying behavior, call `.copy` on the resulting object. {pr}`1114` {user}`ivirshup`
 
-```{rubric} Other updates
-```
+#### Other updates
 
 * Bump minimum python version to 3.9 {pr}`1117` {user}`flying-sheep`
 
-```{rubric} Deprecations
-```
+#### Deprecations
 
 * Deprecate `anndata.read`, which was just an alias for {func}`anndata.read_h5ad` {pr}`1108` {user}`ivirshup`.
 * `dtype` argument to `AnnData` constructor is now deprecated {pr}`1153` {user}`ivirshup`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Fix shape inference on initialization when `X=None` is specified {pr}`1121` {user}`flying-sheep`
diff --git a/docs/release-notes/0.10.1.md b/docs/release-notes/0.10.1.md
@@ -1,6 +1,6 @@
+(v0.10.1)=
 ### 0.10.1 {small}`2023-10-08`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Fix `ad.concat` erroring when concatenating a categorical and object column {pr}`1171` {user}`ivirshup`
diff --git a/docs/release-notes/0.10.2.md b/docs/release-notes/0.10.2.md
@@ -1,7 +1,7 @@
+(v0.10.2)=
 ### 0.10.2 {small}`2023-10-11`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Added compatibility layer for packages relying on `anndata._core.sparse_dataset.SparseDataset`.
   Note that this API is *deprecated* and new code should use {class}`~anndata.experimental.CSRDataset`, {class}`~anndata.experimental.CSCDataset`, and {func}`~anndata.experimental.sparse_dataset` instead.
@@ -11,7 +11,6 @@
 * `as_dense` argument of `write_h5ad` no longer writes an array without encoding metadata {pr}`1193` {user}`flying-sheep`
 
 
-```{rubric} Performance
-```
+#### Performance
 
 * Improved performance of `concat_on_disk` with dense arrays in some cases {pr}`1169` {user}`selmanozleyen`
diff --git a/docs/release-notes/0.10.3.md b/docs/release-notes/0.10.3.md
@@ -1,14 +1,12 @@
+(v0.10.3)=
 ### 0.10.3 {small}`2023-10-31`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 * Prevent pandas from causing infinite recursion when setting a slice of a categorical column {pr}`1211` {user}`flying-sheep`
 
-```{rubric} Documentation
-```
+#### Documentation
 * Stop showing “Support for Awkward Arrays is currently experimental” warnings when
   reading, concatenating, slicing, or transposing AnnData objects {pr}`1182` {user}`flying-sheep`
 
-```{rubric} Other updates
-```
+#### Other updates
 * Fail canary CI job when tests raise unexpected warnings. {pr}`1182` {user}`flying-sheep`
diff --git a/docs/release-notes/0.10.4.md b/docs/release-notes/0.10.4.md
@@ -1,14 +1,13 @@
+(v0.10.4)=
 ### 0.10.4 {small}`2024-01-04`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 * Only try to use `Categorical.map(na_action=…)` in actually supported Pandas ≥2.1 {pr}`1226` {user}`flying-sheep`
 * `AnnData.__sizeof__()` support for backed datasets {pr}`1230` {user}`Neah-Ko`
 * `adata[:, []]` now returns an `AnnData` object empty on the appropriate dimensions instead of erroring {pr}`1243` {user}`ilan-gold`
 * `adata.X[mask]` works in newer `numpy` versions when `X` is `backed` {pr}`1255` {user}`ilan-gold`
 * `adata.X[...]` fixed for `X` as a `BaseCompressedSparseDataset` with `zarr` backend {pr}`1265` {user}`ilan-gold`
 * Improve read/write error reporting {pr}`1273` {user}`flying-sheep`
 
-```{rubric} Documentation
-```
+#### Documentation
 * Improve aligned mapping error messages {pr}`1252` {user}`flying-sheep`
diff --git a/docs/release-notes/0.10.5.md b/docs/release-notes/0.10.5.md
@@ -1,19 +1,17 @@
+(v0.10.5)=
 ### 0.10.5 {small}`2024-01-25`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Fix outer concatenation along variables when only a subset of objects had an entry in layers {pr}`1291` {user}`ivirshup`
 * Fix comparison of >2d arrays in `uns` during concatenation {pr}`1300` {user}`ivirshup`
 * Fix IO with awkward array version 2.5.2 {pr}`1328` {user}`ivirshup`
 * Fix bug (introduced in 0.10.4) where indexing an AnnData with `list[bool]` would return the wrong result {pr}`1332` {user}`ivirshup`
 
-```{rubric} Documentation
-```
+#### Documentation
 * Re-add search-as-you-type, this time via `readthedocs-sphinx-search` {pr}`1311` {user}`flying-sheep`
 
-```{rubric} Performance
-```
+#### Performance
 
 * `BaseCompressedSparseDataset`'s `indptr` is cached {pr}`1266` {user}`ilan-gold`
 * Improved performance when indexing backed sparse matrices with boolean masks along their major axis {pr}`1233` {user}`ilan-gold`
diff --git a/docs/release-notes/0.10.6.md b/docs/release-notes/0.10.6.md
@@ -1,7 +1,7 @@
+(v0.10.6)=
 ### 0.10.6 {small}`2024-03-11`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Defer import of zarr in test helpers, as scanpy CI job relies on them {pr}`1343` {user}`ilan-gold`
 * Writing a dataframe with non-unique column names now throws an error, instead of silently overwriting {pr}`1335` {user}`ivirshup`
@@ -11,13 +11,11 @@
 * Modified `ValueError` message for invalid `.X` during construction to show more helpful list instead of ambiguous `__name__` {pr}`1395` {user}`eroell`
 * Pin `array-api-compat!=1.5` to avoid incorrect implementation of `asarray` {pr}`1411` {user}`ivirshup`
 
-```{rubric} Documentation
-```
+#### Documentation
 
 * Type hints and docstrings for `.to_df` method are updated and fixed {pr}`1402` {user}`WeilerP`
 
-```{rubric} Development
-```
+#### Development
 
 * `anndata`'s CI now tests against minimum versions of it's dependencies. As a result, several dependencies had their minimum required version bumped. See diff for details {pr}`1314` {user}`ivirshup`
 * `anndata` now tests against Python 3.12 {pr}`1373` {user}`ivirshup`
diff --git a/docs/release-notes/0.10.7.md b/docs/release-notes/0.10.7.md
@@ -1,15 +1,11 @@
+(v0.10.7)=
 ### 0.10.7 {small}`2024-04-09`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Handle upstream `numcodecs` bug where read-only string arrays cannot be encoded {user}`ivirshup` {pr}`1421`
 * Use in-memory sparse matrix directly to fix compatibility with `scipy` `1.13` {user}`ilan-gold` {pr}`1435`
 
-```{rubric} Documentation
-```
-
-```{rubric} Performance
-```
+#### Performance
 
 * Remove `vindex` for subsetting `dask.array.Array` because of its slowness and memory consumption {user}`ilan-gold` {pr}`1432`
diff --git a/docs/release-notes/0.10.8.md b/docs/release-notes/0.10.8.md
@@ -1,13 +1,12 @@
+(0.10.8)=
 ### 0.10.8 {small}`2024-06-20`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Write out `64bit` indptr when appropriate for {func}`~anndata.experimental.concat_on_disk` {pr}`1493` {user}`ilan-gold`
 * Support for Numpy 2 {pr}`1499` {user}`flying-sheep`
 * Fix {func}`~anndata.experimental.sparse_dataset` docstring test on account of new {mod}`scipy` version {pr}`1514` {user}`ilan-gold`
 
-```{rubric} Documentation
-```
+#### Documentation
 
 * Improved example for {func}`~anndata.experimental.sparse_dataset` {pr}`1468` {user}`ivirshup`
diff --git a/docs/release-notes/0.10.9.md b/docs/release-notes/0.10.9.md
@@ -1,14 +1,12 @@
+(0.10.9)=
 ### 0.10.9 {small}`the future`
 
-```{rubric} Bugfix
-```
+#### Bugfix
 
 * Coerce {class}`numpy.matrix` classes to arrays when trying to store them in `AnnData` {pr}`1516` {user}`flying-sheep`
 * Fix for setting a dense `X` view with a sparse matrix {pr}`1532` {user}`ilan-gold`
 * Upper bound {mod}`numpy` for `gpu` installation on account of https://github.com/cupy/cupy/issues/8391 {pr}`1540` {user}`ilan-gold`
 
-```{rubric} Documentation
-```
+#### Documentation
 
-```{rubric} Performance
-```
+#### Performance
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}`23 December, 2017`
 
 - read/write [.loom](https://loompy.org) files

diff --git a/docs/release-notes/0.5.0.md b/docs/release-notes/0.5.0.md
@@ -1,3 +1,4 @@
+(v0.5.0)=
 ### 0.5.0 {small}`9 February, 2018`
 
 - inform about duplicates in {class}`~anndata.AnnData.var_names` and resolve them using {func}`~anndata.AnnData.var_names_make_unique`

diff --git a/docs/release-notes/0.6.0.md b/docs/release-notes/0.6.0.md
@@ -1,28 +1,4 @@
-### 0.6.\* {small}`2019-*-*`
-
-- better support for aligned mappings (obsm, varm, layers)
-  `0.6.22` {pr}`155` {smaller}`I Virshup`
-- convenience accessors {func}`~anndata.AnnData.obs_vector`, {func}`~anndata.AnnData.var_vector` for 1d arrays.
-  `0.6.21` {pr}`144` {smaller}`I Virshup`
-- compatibility with Scipy >=1.3 by removing `IndexMixin` dependency.
-  `0.6.20` {pr}`151` {smaller}`P Angerer`
-- bug fix for second-indexing into views.
-  `0.6.19` {smaller}`P Angerer`
-- bug fix for reading excel files.
-  `0.6.19` {smaller}`A Wolf`
-- changed default compression to `None` in {func}`~anndata.AnnData.write_h5ad` to speed up read and write, disk space use is usually less critical.
-  `0.6.16` {smaller}`A Wolf`
-- maintain dtype upon copy.
-  `0.6.13` {smaller}`A Wolf`
-- {attr}`~anndata.AnnData.layers` inspired by [.loom](https://loompy.org) files allows their information lossless reading via {func}`~anndata.read_loom`.
-  `0.6.7`–`0.6.9` {pr}`46` & {pr}`48` {smaller}`S Rybakov`
-- support for reading zarr files: {func}`~anndata.read_zarr`
-  `0.6.7` {pr}`38` {smaller}`T White`
-- initialization from pandas DataFrames
-  `0.6.` {smaller}`A Wolf`
-- iteration over chunks {func}`~anndata.AnnData.chunked_X` and {func}`~anndata.AnnData.chunk_X`
-  `0.6.1` {pr}`20` {smaller}`S Rybakov`
-
+(v0.6.0)=
 ### 0.6.0 {small}`1 May, 2018`
 
 - compatibility with Seurat converter

diff --git a/docs/release-notes/0.6.x.md b/docs/release-notes/0.6.x.md
@@ -0,0 +1,25 @@
+(v0.6.x)=
+### 0.6.\* {small}`2019-*-*`
+
+- better support for aligned mappings (obsm, varm, layers)
+  `0.6.22` {pr}`155` {smaller}`I Virshup`
+- convenience accessors {func}`~anndata.AnnData.obs_vector`, {func}`~anndata.AnnData.var_vector` for 1d arrays.
+  `0.6.21` {pr}`144` {smaller}`I Virshup`
+- compatibility with Scipy >=1.3 by removing `IndexMixin` dependency.
+  `0.6.20` {pr}`151` {smaller}`P Angerer`
+- bug fix for second-indexing into views.
+  `0.6.19` {smaller}`P Angerer`
+- bug fix for reading excel files.
+  `0.6.19` {smaller}`A Wolf`
+- changed default compression to `None` in {func}`~anndata.AnnData.write_h5ad` to speed up read and write, disk space use is usually less critical.
+  `0.6.16` {smaller}`A Wolf`
+- maintain dtype upon copy.
+  `0.6.13` {smaller}`A Wolf`
+- {attr}`~anndata.AnnData.layers` inspired by [.loom](https://loompy.org) files allows their information lossless reading via {func}`~anndata.read_loom`.
+  `0.6.7`–`0.6.9` {pr}`46` & {pr}`48` {smaller}`S Rybakov`
+- support for reading zarr files: {func}`~anndata.read_zarr`
+  `0.6.7` {pr}`38` {smaller}`T White`
+- initialization from pandas DataFrames
+  `0.6.` {smaller}`A Wolf`
+- iteration over chunks {func}`~anndata.AnnData.chunked_X` and {func}`~anndata.AnnData.chunk_X`
+  `0.6.1` {pr}`20` {smaller}`S Rybakov`
diff --git a/docs/release-notes/0.7.0.md b/docs/release-notes/0.7.0.md
@@ -1,3 +1,4 @@
+(v0.7.0)=
 ### 0.7.0 {small}`22 January, 2020`
 
 ```{warning}
@@ -9,35 +10,31 @@ Breaking changes introduced between `0.6.22.post1` and `0.7`:
 - The old deprecated attributes `.smp*`. `.add` and `.data` have been removed.
 ```
 
-~~~{rubric} View overhaul {pr}`164`
-~~~
+#### View overhaul {pr}`164`
 
 - Indexing into a view no longer keeps a reference to intermediate view, see {issue}`62`.
 - Views are now lazy. Elements of view of AnnData are not indexed until they’re accessed.
 - Indexing with scalars no longer reduces dimensionality of contained arrays, see {issue}`145`.
 - All elements of AnnData should now follow the same rules about how they’re subset, see {issue}`145`.
 - Can now index by observations and variables at the same time.
 
-~~~{rubric} IO overhaul {pr}`167`
-~~~
+#### IO overhaul {pr}`167`
 
 - Reading and writing has been overhauled for simplification and speed.
 - Time and memory usage can be half of previous in typical use cases
 - Zarr backend now supports sparse arrays, and generally is closer to having the same features as HDF5.
 - Backed mode should see significant speed and memory improvements for access along compressed dimensions and IO. PR {pr}`241`.
 - {class}`~pandas.Categorical`s can now be ordered (PR {pr}`230`) and written to disk with a large number of categories (PR {pr}`217`).
 
-~~~{rubric} Mapping attributes overhaul {smaller}`(obsm, varm, layers, ...)`
-~~~
+#### Mapping attributes overhaul {smaller}`(obsm, varm, layers, ...)`
 
 - New attributes {attr}`~anndata.AnnData.obsp` and {attr}`~anndata.AnnData.varp` have been added for two dimensional arrays where each axis corresponds to a single axis of the AnnData object. PR {pr}`207`.
 - These are intended to store values like cell-by-cell graphs, which are currently stored in {attr}`~anndata.AnnData.uns`.
 - Sparse arrays are now allowed as values in all mapping attributes.
 - DataFrames are now allowed as values in {attr}`~anndata.AnnData.obsm` and {attr}`~anndata.AnnData.varm`.
 - All mapping attributes now share an implementation and will have the same behaviour. PR {pr}`164`.
 
-```{rubric} Miscellaneous improvements
-```
+#### Miscellaneous improvements
 
 - Mapping attributes now have ipython tab completion (e.g. `adata.obsm["\\t` can provide suggestions) PR {pr}`183`.
 - {class}`~anndata.AnnData` attributes are now delete-able (e.g. `del adata.raw`) PR {pr}`242`.