Doc: Examples per Version (#1821)

ax3l · web-flow · commit c734fb50af4e · 2025-12-17T16:59:42.000-08:00
Link the examples in the manual corresponding to the current version
of the manual. Before this, we always linked to `dev`, which can
cause confusion when working with a stable release.
diff --git a/docs/source/usage/11_particle_dataframe.py b/docs/source/usage/11_particle_dataframe.py
@@ -0,0 +1 @@
+../../../examples/11_particle_dataframe.py
diff --git a/docs/source/usage/12_span_write.cpp b/docs/source/usage/12_span_write.cpp
@@ -0,0 +1 @@
+../../../examples/12_span_write.cpp
diff --git a/docs/source/usage/12_span_write.py b/docs/source/usage/12_span_write.py
@@ -0,0 +1 @@
+../../../examples/12_span_write.py
diff --git a/docs/source/usage/1_structure.cpp b/docs/source/usage/1_structure.cpp
@@ -0,0 +1 @@
+../../../examples/1_structure.cpp
diff --git a/docs/source/usage/6_dump_filebased_series.cpp b/docs/source/usage/6_dump_filebased_series.cpp
@@ -0,0 +1 @@
+../../../examples/6_dump_filebased_series.cpp
diff --git a/docs/source/usage/7_extended_write_serial.cpp b/docs/source/usage/7_extended_write_serial.cpp
@@ -0,0 +1 @@
+../../../examples/7_extended_write_serial.cpp
diff --git a/docs/source/usage/7_extended_write_serial.py b/docs/source/usage/7_extended_write_serial.py
@@ -0,0 +1 @@
+../../../examples/7_extended_write_serial.py
diff --git a/docs/source/usage/8_benchmark_parallel.cpp b/docs/source/usage/8_benchmark_parallel.cpp
@@ -0,0 +1 @@
+../../../examples/8_benchmark_parallel.cpp
diff --git a/docs/source/usage/8a_benchmark_write_parallel.cpp b/docs/source/usage/8a_benchmark_write_parallel.cpp
@@ -0,0 +1 @@
+../../../examples/8a_benchmark_write_parallel.cpp
diff --git a/docs/source/usage/8b_benchmark_read_parallel.cpp b/docs/source/usage/8b_benchmark_read_parallel.cpp
@@ -0,0 +1 @@
+../../../examples/8b_benchmark_read_parallel.cpp
diff --git a/docs/source/usage/9_particle_write_serial.py b/docs/source/usage/9_particle_write_serial.py
@@ -0,0 +1 @@
+../../../examples/9_particle_write_serial.py
diff --git a/docs/source/usage/examples.rst b/docs/source/usage/examples.rst
@@ -11,41 +11,41 @@ The following command will automatically install those into ``samples/`` on Linu
 C++
 ---
 
-- `1_structure.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/1_structure.cpp>`_: creating a first series
-- `2_read_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/2_read_serial.cpp>`_: reading a mesh & a particle species
-- `2a_read_thetaMode_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/2a_read_thetaMode_serial.cpp>`_: read an azimuthally decomposed mesh (and reconstruct it)
-- `3_write_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/3_write_serial.cpp>`_: writing a mesh
-- `3a_write_thetaMode_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/3a_write_thetaMode_serial.cpp>`_: write an azimuthally decomposed mesh
-- `3b_write_resizable_particles.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/3b_write_resizable_particles.cpp>`_: write particles in a resizeable dataset
-- `4_read_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/4_read_parallel.cpp>`_: MPI-parallel mesh read
-- `5_write_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/5_write_parallel.cpp>`_: MPI-parallel mesh write
-- `6_dump_filebased_series.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/6_dump_filebased_series.cpp>`_: detailed reading with a file-based series
-- `7_extended_write_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/7_extended_write_serial.cpp>`_: particle writing with patches and constant records
-- `10_streaming_write.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/10_streaming_write.cpp>`_ / `10_streaming_read.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/10_streaming_read.cpp>`_: ADIOS2 data streaming
-- `12_span_write.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/12_span_write.cpp>`_: using the span-based API to save memory when writing
+- :download:`1_structure.cpp <1_structure.cpp>`: creating a first series
+- :download:`2_read_serial.cpp <2_read_serial.cpp>`: reading a mesh & a particle species
+- :download:`2a_read_thetaMode_serial.cpp <2a_read_thetaMode_serial.cpp>`: read an azimuthally decomposed mesh (and reconstruct it)
+- :download:`3_write_serial.cpp <3_write_serial.cpp>`: writing a mesh
+- :download:`3a_write_thetaMode_serial.cpp <3a_write_thetaMode_serial.cpp>`: write an azimuthally decomposed mesh
+- :download:`3b_write_resizable_particles.cpp <3b_write_resizable_particles.cpp>`: write particles in a resizeable dataset
+- :download:`4_read_parallel.cpp <4_read_parallel.cpp>`: MPI-parallel mesh read
+- :download:`5_write_parallel.cpp <5_write_parallel.cpp>`: MPI-parallel mesh write
+- :download:`6_dump_filebased_series.cpp <6_dump_filebased_series.cpp>`: detailed reading with a file-based series
+- :download:`7_extended_write_serial.cpp <7_extended_write_serial.cpp>`: particle writing with patches and constant records
+- :download:`10_streaming_write.cpp <10_streaming_write.cpp>` / :download:`10_streaming_read.cpp <10_streaming_read.cpp>`: ADIOS2 data streaming
+- :download:`12_span_write.cpp <12_span_write.cpp>`: using the span-based API to save memory when writing
 
 Benchmarks
 ^^^^^^^^^^
 
-- `8_benchmark_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/8_benchmark_parallel.cpp>`_: a MPI-parallel IO-benchmark
-- `8a_benchmark_write_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/8a_benchmark_write_parallel.cpp>`_: creates 1D/2D/3D arrays, with each rank having a few blocks to write to
-- `8b_benchmark_read_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/8b_benchmark_read_parallel.cpp>`_: read slices of meshes and particles
+- :download:`8_benchmark_parallel.cpp <8_benchmark_parallel.cpp>`: a MPI-parallel IO-benchmark
+- :download:`8a_benchmark_write_parallel.cpp <8a_benchmark_write_parallel.cpp>`: creates 1D/2D/3D arrays, with each rank having a few blocks to write to
+- :download:`8b_benchmark_read_parallel.cpp <8b_benchmark_read_parallel.cpp>`: read slices of meshes and particles
 
 Python
 ------
 
-- `2_read_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/2_read_serial.py>`_: reading a mesh & a particle species
-- `2a_read_thetaMode_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/2a_read_thetaMode_serial.py>`_: reading an azimuthally decomposed mesh (and reconstruct it)
-- `3_write_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/3_write_serial.py>`_: writing a mesh
-- `3a_write_thetaMode_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/3a_write_thetaMode_serial.py>`_: write an azimuthally decomposed mesh
-- `3b_write_resizable_particles.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/3b_write_resizable_particles.py>`_: write particles in a resizeable dataset
-- `4_read_parallel.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/4_read_parallel.py>`_: MPI-parallel mesh read
-- `5_write_parallel.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/5_write_parallel.py>`_: MPI-parallel mesh write
-- `7_extended_write_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/7_extended_write_serial.py>`_: particle writing with patches and constant records
-- `9_particle_write_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/9_particle_write_serial.py>`_: writing particles
-- `10_streaming_write.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/10_streaming_write.py>`_ / `10_streaming_read.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/10_streaming_read.py>`_: ADIOS2 data streaming
-- `11_particle_dataframe.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/11_particle_dataframe.py>`_: reading data into `Pandas <https://pandas.pydata.org>`_ dataframes or `Dask <https://dask.org>`_ for distributed analysis
-- `12_span_write.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/12_span_write.py>`_: using the span-based API to save memory when writing
+- :download:`2_read_serial.py <2_read_serial.py>`: reading a mesh & a particle species
+- :download:`2a_read_thetaMode_serial.py <2a_read_thetaMode_serial.py>`: reading an azimuthally decomposed mesh (and reconstruct it)
+- :download:`3_write_serial.py <3_write_serial.py>`: writing a mesh
+- :download:`3a_write_thetaMode_serial.py <3a_write_thetaMode_serial.py>`: write an azimuthally decomposed mesh
+- :download:`3b_write_resizable_particles.py <3b_write_resizable_particles.py>`: write particles in a resizeable dataset
+- :download:`4_read_parallel.py <4_read_parallel.py>`: MPI-parallel mesh read
+- :download:`5_write_parallel.py <5_write_parallel.py>`: MPI-parallel mesh write
+- :download:`7_extended_write_serial.py <7_extended_write_serial.py>`: particle writing with patches and constant records
+- :download:`9_particle_write_serial.py <9_particle_write_serial.py>`: writing particles
+- :download:`10_streaming_write.py <10_streaming_write.py>` / :download:`10_streaming_read.py <10_streaming_read.py>`: ADIOS2 data streaming
+- :download:`11_particle_dataframe.py <11_particle_dataframe.py>`: reading data into `Pandas <https://pandas.pydata.org>`__ dataframes or `Dask <https://dask.org>`__ for distributed analysis
+- :download:`12_span_write.py <12_span_write.py>`: using the span-based API to save memory when writing
 
 Unit Tests
 ----------

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/11_particle_dataframe.py`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/6_dump_filebased_series.cpp`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/7_extended_write_serial.cpp`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/8_benchmark_parallel.cpp`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/8a_benchmark_write_parallel.cpp`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../examples/8b_benchmark_read_parallel.cpp`