Rework the documentation to be build with sphinx (#1753)

* Move CUB to the new repo_docs * Move libcu++ docs to the new repo_docs * Move Thrust to the new repo_docs Co-authored-by: Georgii Evtushenko <[email protected]>
NVIDIA · Jun 5, 2024 · 42d6e57 · 42d6e57
1 parent 0bfbe60
commit 42d6e57
Show file tree

Hide file tree

Showing 363 changed files with 15,245 additions and 17,347 deletions.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -32,39 +32,24 @@ jobs:
 
       # Build helper image for Thrust/CUB
       - name: Build helper image
-        run: |
-          bash ./docs/make_env.bash "cccl:docs"
-
-      # Build top level docs for CCCL
-      - name: Build landing page
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./docs/jekyll
-          destination: ./_site
+        run: bash ./docs/make_env.bash "cccl:docs"
 
-      # CUB
-      - name: Build CUB docs
-        run: |
-          bash ./docs/build_docs.bash "cccl:docs" /cccl/cub/docs/gen_docs.bash
-          sudo mkdir -p ./_site/cub
-          sudo cp -rf ./cub/docs/_build/docs/CUB/latest/* ./_site/cub
+      # Build all docs
+      - name: Build all docs
+        run: ./docs/gen_docs.bash
 
-      # Libcudacxx
-      - name: Build libcudacxx docs
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./libcudacxx/docs
-          destination: ./_site/libcudacxx
+      # Copy all docs to the right folder
+      - name: Move docs to right folder
 
-      # Thrust
-      - name: Build Thrust markdown in Docker
-        run: bash ./docs/build_docs.bash "cccl:docs" /cccl/thrust/docs/build_docs_locally.bash
-
-      - name: Build Thrust docs
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./thrust/build_docs/github_pages
-          destination: ./_site/thrust
+        run: |
+          mkdir _site
+          cp -rf ./docs/_build/docs/cccl/latest/* _site
+          mkdir _site/cub
+          cp -rf ./docs/_build/docs/cub/latest/* _site/cub
+          mkdir _site/libcudacxx
+          cp -rf ./docs/_build/docs/libcudacxx/latest/* _site/libcudacxx
+          mkdir _site/thrust
+          cp -rf ./docs/_build/docs/thrust/latest/* _site/thrust
 
       # Upload build artifacts
       - name: Upload artifact

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,6 +16,7 @@ Thank you for your interest in contributing to the CUDA C++ Core Libraries (CCCL
 ## Making Changes
 
 1. **Create a New Branch**:
+
    ```bash
    git checkout -b your-feature-branch
    ```
@@ -30,6 +31,7 @@ Thank you for your interest in contributing to the CUDA C++ Core Libraries (CCCL
    ./ci/build_[thrust|cub|libcudacxx].sh -cxx <HOST_COMPILER> -std <CXX_STANDARD> -arch <GPU_ARCHS>
    ./ci/test_[thrust|cub|libcudacxx].sh  -cxx <HOST_COMPILER> -std <CXX_STANDARD> -arch <GPU_ARCHS>
    ```
+
    For more details on building and testing, refer to the [Building and Testing](#building-and-testing) section below.
 
 4. **Commit Changes**:
@@ -43,15 +45,18 @@ Thank you for your interest in contributing to the CUDA C++ Core Libraries (CCCL
 For more information about design and development practices for each CCCL component, refer to the following developer guides:
 
 #### CUB
-- [CUB Developer Guide](cub/docs/developer_overview.rst) - General overview of the design of CUB internals
-- [CUB Test Overview](cub/docs/test_overview.rst) - Overview of how to write CUB unit tests
-- [CUB Tuning Infrastructure](cub/docs/tuning.rst) - Overview of CUB's performance tuning infrastructure
-- [CUB Benchmarks](cub/docs/benchmarking.rst) - Overview of CUB's performance benchmarks
+
+- [CUB Developer Guide](docs/cub/developer_overview.rst) - General overview of the design of CUB internals
+- [CUB Test Overview](docs/cub/test_overview.rst) - Overview of how to write CUB unit tests
+- [CUB Tuning Infrastructure](docs/cub/tuning.rst) - Overview of CUB's performance tuning infrastructure
+- [CUB Benchmarks](docs/cub/benchmarking.rst) - Overview of CUB's performance benchmarks
 
 #### Thrust
+
 Coming soon!
 
 #### libcudacxx
+
 Coming soon!
 
 ## Building and Testing
@@ -61,6 +66,7 @@ CCCL components are header-only libraries. This means there isn't a traditional
 There are multiple options for building and running our tests. Which option you choose depends on your preferences and whether you are using [CCCL's DevContainers](.devcontainer/README.md) (highly recommended!).
 
 ### Using Manual Build Scripts
+
 #### Building
 
 Use the build scripts provided in the `ci/` directory to build tests for each component. Building tests does not require a GPU.
@@ -89,6 +95,7 @@ Use the test scripts provided in the `ci/` directory to run tests for each compo
 ```
 
 **Example:**
+
 ```bash
 ./ci/test_cub.sh -cxx g++ -std 14 -arch "70;75;80-virtual"
 ```
@@ -139,7 +146,7 @@ As a common example, the presets are currently always `60;70;80` for `CMAKE_CUDA
 cmake --preset=thrust-cpp20 "-DCMAKE_CUDA_ARCHITECTURES=89"
 ```
 
-> __Note__: Either using the `cmake` command from within the root directory or from within the build directory works, but will behave in slightly different ways. Building and running tests from the build directory will compile every target and run all of the tests configured in the configure step. Doing so from the root directory using the `--preset=<test_preset>` option will build and run a subset of configured targets and tests.
+> **Note**: Either using the `cmake` command from within the root directory or from within the build directory works, but will behave in slightly different ways. Building and running tests from the build directory will compile every target and run all of the tests configured in the configure step. Doing so from the root directory using the `--preset=<test_preset>` option will build and run a subset of configured targets and tests.
 
 #### Using CMake Presets via VS Code GUI extension (Recommended when using DevContainers)
 
@@ -233,9 +240,10 @@ Once submitted, maintainers will be automatically assigned to review the pull re
 For constructive feedback and effective communication during reviews, we recommend following [Conventional Comments](https://conventionalcomments.org/).
 
 Further recommended reading for successful PR reviews:
+
 - [How to Do Code Reviews Like a Human (Part One)](https://mtlynch.io/human-code-reviews-1/)
 - [How to Do Code Reviews Like a Human (Part Two)](https://mtlynch.io/human-code-reviews-2/)
 
-## Thank You!
+## Thank You
 
 Your contributions enhance CCCL for the entire community. We appreciate your effort and collaboration!
diff --git a/cub/cub/block/block_adjacent_difference.cuh b/cub/cub/block/block_adjacent_difference.cuh
@@ -1052,7 +1052,7 @@ public:
 #endif // DOXYGEN_SHOULD_SKIP_THIS
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeads
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeads
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft instead.
    *
    * @param[out] output
@@ -1073,7 +1073,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeads
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeads
    *              APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft instead.
    *
    * @param[out] output
@@ -1098,7 +1098,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractRight instead.
    *
    * @param output
@@ -1133,7 +1133,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractRight instead.
    *
    * @param[out] output
@@ -1171,7 +1171,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft or
    *             cub::BlockAdjacentDifference::SubtractRight instead.
    *
@@ -1230,7 +1230,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft or
    *             cub::BlockAdjacentDifference::SubtractRight instead.
    *
@@ -1293,7 +1293,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft or
    *             cub::BlockAdjacentDifference::SubtractRight instead.
    *
@@ -1352,7 +1352,7 @@ public:
   }
 
   /**
-   * @deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
+   *  deprecated [Since 1.14.0] The cub::BlockAdjacentDifference::FlagHeadsAndTails
    *             APIs are deprecated. Use cub::BlockAdjacentDifference::SubtractLeft or
    *             cub::BlockAdjacentDifference::SubtractRight instead.
    *