Merge pull request #631 from dalg24/overhaul_build_instructions_and_g…

…eneral_organization Major overhaul of build instructions and reorganizing sections
kokkos · Feb 18, 2025 · 772abee · 772abee
2 parents 8dd8f7e + 11a2cce
commit 772abee
Show file tree

Hide file tree

Showing 23 changed files with 585 additions and 204 deletions.
diff --git a/.github/workflows/typos.yml b/.github/workflows/typos.yml
@@ -13,5 +13,5 @@ jobs:
       uses: crate-ci/typos@v1.23.6
       with:
         write_changes: true
-        files: ./docs/source/ProgrammingGuide/ ./docs/source/API/ ./docs/source/*.rst ./docs/source/*.md
+        files: ./docs/source/ProgrammingGuide/ ./docs/source/API/ ./docs/source/*.rst
         config: ./.typos.toml
diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst
@@ -1,5 +1,5 @@
-API: Algorithms
-###############
+Algorithms API
+##############
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/source/API/containers-index.rst b/docs/source/API/containers-index.rst
@@ -1,5 +1,5 @@
-API: Containers
-###############
+Containers API
+##############
 
 .. list-table::
    :widths: 25 75
@@ -15,13 +15,13 @@ API: Containers
      - DynamicView comment.
    * - `DynRankView <containers/DynRankView.html>`__
      - Kokkos Runtime-determined-dimension DynRankView class.
-   * - `Offset-View <containers/Offset-View.html>`__
+   * - `OffsetView <containers/Offset-View.html>`__
      - OffsetView comment.
    * - `ScatterView <containers/ScatterView.html>`__
      - ScatterView comment.
    * - `StaticCrsGraph <containers/StaticCrsGraph.html>`__
-     - StaticCrsGraph comment.
-   * - `Unordered-Map <containers/Unordered-Map.html>`__
+     - [DEPRECATED] StaticCrsGraph compressed raw storage graph
+   * - `UnorderedMap <containers/Unordered-Map.html>`__
      - UnorderedMap comment.
    * - `vector <containers/vector.html>`__
      - [DEPRECATED] std::vector compatible implementation that works with non-host memory spaces.

diff --git a/docs/source/API/containers/StaticCrsGraph.rst b/docs/source/API/containers/StaticCrsGraph.rst
@@ -1,8 +1,10 @@
 
-``StaticCrsGraph``
-==================
+``StaticCrsGraph`` [DEPRECATED]
+===============================
 
-Header file: ``<Kokkos_StaticCrsGraph.hpp>``
+Header file: ``<Kokkos_StaticCrsGraph.hpp>`` (deprecated since Kokkos 4.5)
+
+``StaticCrsGraph`` was moved to KokkosKernels.
 
 The StaticCrsGraph is a Compressed row storage array with the row map, the column indices and the non-zero entries stored in 3 different Kokkos::Views.  Appropriate types and functions are provided to simplify manipulation and access to CRS data on either a host or device.
 

diff --git a/docs/source/API/core-index.rst b/docs/source/API/core-index.rst
@@ -1,5 +1,5 @@
-API: Core
-#########
+Core API
+########
 
 .. list-table::
    :widths: 20 80

diff --git a/docs/source/API/simd-index.rst b/docs/source/API/simd-index.rst
@@ -1,5 +1,5 @@
-API: SIMD
-###############
+SIMD API
+########
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/source/ProgrammingGuide/Compiling.md b/docs/source/ProgrammingGuide/Compiling.md
@@ -127,7 +127,7 @@ There are numerous device backends, options, and architecture-specific optimizat
  -DCMAKE_INSTALL_PREFIX=${my_install_folder} \
  -DKokkos_ENABLE_OPENMP=On
 ```
-which activates the OpenMP backend. All the options controlling device backends, options, architectures, and third-party libraries (TPLs) are given in [CMake Keywords](../keywords).
+which activates the OpenMP backend. All the options controlling device backends, options, architectures, and third-party libraries (TPLs) are given in the [Configuration Guide](../get-started/configuration-guide).
 
 
 ### Spack
@@ -192,15 +192,15 @@ endif()
 
 ### Kokkos CMake Keyword Listing
 
-Please see the [documentation page with all keywords](../keywords).
+Please see the [documentation page with all keywords](../get-started/configuration-guide).
 
 ## 4.3 Using Trilinos' CMake build system
 
 The Trilinos project (see [`trilinos.org`](https://trilinos.org) and github for the [source code](https://github.com/trilinos/Trilinos) repository) is an effort to develop algorithms and enabling technologies within an object-oriented software framework for the solution of large-scale, complex multiphysics engineering and scientific problems. Trilinos is organized into packages. Even though Kokkos is a stand-alone software project, Trilinos uses Kokkos extensively. Thus, Trilinos' source code includes Kokkos' source code, and builds Kokkos as part of its build process.
 
 Trilinos' build system uses CMake. Thus, to build Kokkos as part of Trilinos, you must first install CMake (version `3.17` or newer). To enable Kokkos when building Trilinos, set the CMake option `Trilinos_ENABLE_Kokkos`. Trilinos' build system lets packages express dependencies on other packages or external libraries. If you enable any Trilinos package (e.g., Tpetra) that has a required dependency on Kokkos, Trilinos will enable Kokkos automatically. Configuration macros are automatically inferred from Trilinos settings. For example, if the CMake option `Trilinos_ENABLE_OpenMP` is `ON`, Trilinos will define the macro `Kokkos_ENABLE_OPENMP`. Trilinos' build system will autogenerate the previously mentioned `KokkosCore_config.h` file that contains those macros.
 
-Trilinos' CMake build system utilizes Kokkos' build system to set compiler flags, compiler options, architectures, etc. CMake variables `CMAKE_CXX_COMPILER`, `CMAKE_C_COMPILER`, and `CMAKE_FORTRAN_COMPILER` are used to specify the compiler. To configure Trilinos for various architectures, with Kokkos enabled, the CMake variable `Kokkos_ARCH_<ArchCode>` should be set, matching ArchCode to the appropriate architecture as specified in [Architecture Keywords](../keywords).
+Trilinos' CMake build system utilizes Kokkos' build system to set compiler flags, compiler options, architectures, etc. CMake variables `CMAKE_CXX_COMPILER`, `CMAKE_C_COMPILER`, and `CMAKE_FORTRAN_COMPILER` are used to specify the compiler. To configure Trilinos for various architectures, with Kokkos enabled, the CMake variable `Kokkos_ARCH_<ArchCode>` should be set, matching ArchCode to the appropriate architecture as specified in [Architecture Keywords](../get-started/configuration-guide).
 
 For example, `Kokkos_ARCH_HSW` sets the architecture variables for a machine with Intel Haswell CPUs. Also, when setting the `Kokkos_ARCH_<ArchCode>` variable it is not necessary to pass required architecture-specific flags to CMake, for example via the `CMAKE_CXX_FLAGS` variable.
 

diff --git a/docs/source/api-references.rst b/docs/source/api-references.rst
@@ -0,0 +1,39 @@
+API References
+##############
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   API/core-index
+   API/algorithms-index
+   API/containers-index
+   API/simd-index
+   API/alphabetical
+   deprecations
+
+:doc:`API/core-index`
+~~~~~~~~~~~~~~~~~~~~~
+The fundamental abstractions for execution (``parallel_for``,
+``parallel_reduce``, ``parallel_scan``) and data (``View``).
+
+:doc:`API/algorithms-index`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Utility classes for pseudo-random number generation, sorting algorthms,
+STL-like parallel algorithms.
+
+:doc:`API/containers-index`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Exotic view-based containers, such as ``DualView``, ``ScatterView``, or ``OffsetView``.
+
+:doc:`API/simd-index`
+~~~~~~~~~~~~~~~~~~~~~
+Data-parallel vector types.
+
+:doc:`Alphabetical <API/alphabetical>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+List of all library features in alphabetical order.
+
+:doc:`deprecations`
+~~~~~~~~~~~~~~~~~~~
+List of obsolete features that have been deprecated and/or removed.
diff --git a/docs/source/building.md b/docs/source/building.md
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -7,6 +7,7 @@ Contributing
 
    templates/index
    developer-guides/index
+   testing-and-issue-tracking
 
 We are open and try to encourage contributions from external developers.
 To do so please first open an issue describing the contribution and then
@@ -27,3 +28,11 @@ Contributing Documentation
 Please see the `README <https://github.com/kokkos/kokkos-core-wiki/blob/main/README.md>`_ for general instructions on building the documentation.
 
 To make it easier to contribute API documentation, we have a page of documentation templates :doc:`here <templates/index>`
+
+Developers' Corner
+------------------
+
+* :doc:`Developer Guide  <developer-guides/index>`
+
+* :doc:`Kokkos Panning and Testing <testing-and-issue-tracking>`
+
diff --git a/docs/source/deprecation_page.rst → docs/source/deprecations.rst b/docs/source/deprecation_page.rst → docs/source/deprecations.rst
diff --git a/docs/source/get-started.rst b/docs/source/get-started.rst
@@ -0,0 +1,51 @@
+Get Started
+###########
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   get-started/quick-start
+   get-started/requirements
+   get-started/integrating-kokkos-into-your-cmake-project
+   get-started/building-from-source
+   get-started/configuration-guide
+   get-started/package-managers
+
+
+Want to try Kokkos right away?  Check it out on `Compiler Explorer
+<https://godbolt.org/z/svrE563Kn>`_.
+
+:doc:`Quick Start <get-started/quick-start>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This guide provides the minimal first-steps instructions to get started with a
+CMake project and start writting Kokkos code.
+
+:doc:`Integrating Kokkos into Your Project <get-started/integrating-kokkos-into-your-cmake-project>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This guide discusses in details how to setup your project to use Kokkos.
+
+:doc:`Requirements <get-started/requirements>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This page details the supported versions of various components required to
+build and use Kokkos, including build systems, vendor toolchains, compilers,
+C++ standards, and target architectures (both CPU and GPU).  A comprehensive
+table lists compatible combinations of these components.
+
+:doc:`Building from Source <get-started/building-from-source>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This guide provides instructions for downloading the Kokkos source code,
+configuring to generate the build system, compiling the library, and installing
+it on your system.
+
+:doc:`Configuration Guide <get-started/configuration-guide>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This page provides a comprehensive reference for all Kokkos configuration
+options, including backend selection for targeting specific hardware setups,
+general and backend-specific CMake options, control over third-party library
+usage, and a complete list of supported CPU and GPU architectures.
+
+:doc:`Package Managers <get-started/package-managers>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This page lists package managers that offer pre-built Kokkos packages,
+providing a convenient alternative to building from source.