Doc reorganization (#839)

Author: tpadioleau

docs/CMakeLists.txt

@@ -77,13 +77,14 @@ set(DOXYGEN_HTML_EXTRA_FILES
 
 doxygen_add_docs(
     doc
-    "${CMAKE_CURRENT_SOURCE_DIR}/About.md"
+    "${CMAKE_CURRENT_SOURCE_DIR}/about.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/first_steps.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/going_further.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/uniform_heat_equation.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/non_uniform_heat_equation.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/concepts.md"
     "${CMAKE_CURRENT_SOURCE_DIR}/heat_equation_spectral.md"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples.md"
     "${DDC_SOURCE_DIR}/include/ddc/"
     ALL
 )

docs/About.md docs/about.mddocs/About.md renamed to docs/about.md

@@ -1,11 +1,11 @@
+# About {#mainpage}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# About {#mainpage}
-
 %DDC is the discrete domain computation library, a C++-17 library that aims to offer to the C++/MPI
 world an equivalent to the
 [`xarray.DataArray`](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html)/[`dask.Array`](https://docs.dask.org/en/stable/array.html)

docs/concepts.md

@@ -1,11 +1,11 @@
+# DDC concepts
+
 <!--
 Copyright (C) The ddc development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# DDC concepts
-
 DDC introduces labels in the form of dimensions and attributes on top of Kokkos arrays, which offer a more intuitive and less error-prone development experience.
 
 Using Kokkos, the indices of views are weakly typed, meaning that each index is a simple integer. Let's consider a multidimensional view intended to represent a physical quantity, such as a temperature field for example. The first index represents the temperature along the \f$x\f$ axis, and the second index represents the temperature along the \f$y\f$ axis. As both indices are simple integers, they may be swapped by mistake. The code would compile successfully, but the result would be incorrect, and the source of the error would be difficult to trace.

docs/examples.md

@@ -0,0 +1,11 @@
+# Examples
+
+<!--
+Copyright (C) The DDC development team, see COPYRIGHT.md file
+
+SPDX-License-Identifier: MIT
+-->
+
+- \subpage first_steps
+- \subpage going_further
+- \subpage heat_equation_spectral

docs/first_steps.md

@@ -1,11 +1,11 @@
+# The uniform heat equation {#first_steps}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# Commented example: the uniform heat equation {#first_steps}
-
 In \subpage uniform_heat_equation "examples/uniform_heat_equation.cpp" is a DDC example implementing a forward
 finite-difference solver for the heat equation over a rectangle 2D domain with periodic boundary
 conditions.

docs/going_further.md

@@ -1,11 +1,11 @@
+# The non uniform heat equation {#going_further}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# Commented example: the non uniform heat equation {#going_further}
-
 In \subpage non_uniform_heat_equation "examples/non_uniform_heat_equation.cpp" is a DDC example implementing a forward
 finite-difference solver for the heat equation over a rectangle 2D domain with periodic boundary
 conditions and non-uniform space discretization.

docs/heat_equation_spectral.md

@@ -1,9 +1,9 @@
+# examples/heat_equation_spectral.cpp {#heat_equation_spectral}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# examples/heat_equation_spectral.cpp {#heat_equation_spectral}
-
 \include{lineno} heat_equation_spectral.cpp

docs/non_uniform_heat_equation.md

@@ -1,9 +1,9 @@
+# examples/non_uniform_heat_equation.cpp {#non_uniform_heat_equation}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# examples/non_uniform_heat_equation.cpp {#non_uniform_heat_equation}
-
 \include{lineno} non_uniform_heat_equation.cpp

docs/uniform_heat_equation.md

@@ -1,9 +1,9 @@
+# examples/uniform_heat_equation.cpp {#uniform_heat_equation}
+
 <!--
 Copyright (C) The DDC development team, see COPYRIGHT.md file
 
 SPDX-License-Identifier: MIT
 -->
 
-# examples/uniform_heat_equation.cpp {#uniform_heat_equation}
-
 \include{lineno} uniform_heat_equation.cpp