docs: Add development guideline section

CONTRIBUTING.md

@@ -1,31 +1,3 @@
 # Contributing
 
-Thank you for taking the time to contribute to the project. The following set of guidelines will help you with your contribution and explain the review process.
-
-
-## Reporting Bugs / Proposing New Features
-
-If you discover a bug or want to propose a new feature or enhancement to the code or documentation, please check whether the problem has already been reported in the [Issues](https://github.com/stotko/stdgpu/issues).
-
-If not, open a new issue and state the problem. Please provide a clear summary of the problem, what behavior you have expected and what behavior you have actually observed. If possible, create a *Minimal Reproducable Example* that demonstrates the problem.
-
-
-## Submitting Changes
-
-We also highly welcome code contributions via pull requests. Note that your changes - after acceptance - will be offered under the **Apache 2.0** license. For more information, see the [LICENSE](https://github.com/stotko/stdgpu/blob/master/LICENSE).
-
-To create and submit your changes, follow the standard *Fork & Pull Request Workflow*:
-
-1. Fork the project and switch to a new suitably named branch.
-2. Follow the coding style guidelines. See the [STYLE GUIDE](https://github.com/stotko/stdgpu/blob/master/STYLE_GUIDE.md) for details.
-3. Create one or more commits that reflect the changes you have made. Each commit should be self-contained, atomic and buildable. Therefore, split multiple features into different commits and include fixups in the related commit instead of creating a new one. If you add new functionality, please also add related tests.
-4. Test the changes on your local machine. For this, the provided scripts will help you to build the code and run the unit tests. See the [README](https://github.com/stotko/stdgpu/blob/master/README.md) for details.
-5. Push the branch to your fork.
-6. Open a new pull request and summarize the problem and your solution. If there is a related issue, please mention it too.
-
-Once you have submitted the pull request, your changes will be reviewed. You will receive feedback in two different forms:
-
-1. **Automatic review**. Each pull request will be automatically tested using *Continuous Integration* tools. If a test fails, take a look at the error and fix the problem.
-2. **Manual human review**. In addition, your code will be manually reviewed by the project maintainers. Incorporate their feedback to improve the quality of your contribution.
-
-After the review is complete and all tests pass, your pull request will be accepted and merged.
+Thank you for taking the time to contribute to the project. All guidelines can be found in the [Contributing](https://stotko.github.io/stdgpu/development/contributing.html) section of the documentation.

README.md

@@ -25,15 +25,9 @@
 <a href="https://stotko.github.io/stdgpu" alt="Documentation">
     <img src="https://img.shields.io/badge/docs-Latest-green.svg"/>
 </a>
-<a href="https://github.com/stotko/stdgpu/blob/master/CONTRIBUTING.md" alt="Contributing">
-    <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat"/>
-</a>
 <a href="https://github.com/stotko/stdgpu/blob/master/LICENSE" alt="License">
     <img src="https://img.shields.io/github/license/stotko/stdgpu"/>
 </a>
-<a href="https://github.com/stotko/stdgpu/releases" alt="Latest Release">
-    <img src="https://img.shields.io/github/v/release/stotko/stdgpu"/>
-</a>
 </p>
 
 <!-- end badges -->
@@ -302,7 +296,7 @@ Configuration Option | Effect | Default
 
 ## Contributing
 
-For detailed information on how to contribute, see [`CONTRIBUTING`](https://github.com/stotko/stdgpu/blob/master/CONTRIBUTING.md).
+For detailed information on how to contribute, see the [Contributing](https://stotko.github.io/stdgpu/development/contributing.html) section in the documentation.
 
 
 ## License

docs/development/contributing.md

@@ -0,0 +1,104 @@
+# Contributing
+
+Thank you for your interest into contributing to stdgpu! There are multiple ways for you to contribute and to help advancing the library:
+
+- Report a bug or help triaging existing bugs
+- Propose a new feature that is currently missing
+- Submit a fix for a bug
+- Submit a new feature or an improvement to an existing feature
+- Write some documentation
+
+
+## Reporting Bugs / Proposing New Features
+
+Not all contributions require that you actually submit some code. Simply reporting a bug, which you have discovered, or proposing a feature, that is currently missing and you would like to see, is great way to help with the development of the library.
+
+We track bugs and feature requests with [GitHub Issues](https://github.com/stotko/stdgpu/issues). Before opening a new issue, please check whether the problem has already been reported and respond there.
+
+If your issue has not been reported yet, feel free to open a new issue and describe the problem. Please provide a clear summary of the problem, what behavior you have expected and what behavior you have actually observed. If possible, create a *Minimal Reproducable Example* that demonstrates the problem.
+
+
+## Submitting Bug Fixes / Features / Documentation
+
+We also highly welcome code contributions via [GitHub Pull Requests](https://github.com/stotko/stdgpu/pulls) which --- after acceptance --- will be offered under the **Apache 2.0** license, see the [LICENSE](https://github.com/stotko/stdgpu/blob/master/LICENSE).
+
+To submit your changes, follow the standard *Fork & Pull Request Workflow*:
+
+1. Fork the project and switch to a new suitably named branch.
+3. Create one or more commits that reflect the changes you have made. Each commit should be self-contained, atomic and buildable. Thus, split multiple features into different commits and include fixups in the related commit instead of creating a new one.
+4. If you add new functionality such as a new class or function, please also add respective documentation and tests for it.
+5. Push the branch to your fork.
+6. Open a new pull request with a brief motivation of the problem and how you addressed it in your changes. If there already exists a related [GitHub Issue](https://github.com/stotko/stdgpu/issues), please mention it there as well.
+
+You can find more information for the development of your changes in the [building guide](../index.md#building) as well as on the following pages:
+
+
+:::::{grid} 2 2 3 3
+:gutter: 3 3 4 4
+
+::::{grid-item-card}
+:link: contributing/coding_style
+:link-type: doc
+
+**Coding Style**
+^^^
+How to format the source code.
+
+::::
+
+::::{grid-item-card}
+:link: contributing/documentation
+:link-type: doc
+
+**Documentation**
+^^^
+How to build the documentation.
+
+::::
+
+::::{grid-item-card}
+:link: contributing/tests
+:link-type: doc
+
+**Tests**
+^^^
+How to run the unit tests.
+
+::::
+
+:::::
+
+
+After you have submitted a pull request, your changes will be reviewed and you will receive some feedback:
+
+1. **Automatic review**. Each pull request will be automatically tested using *Continuous Integration* tools. If a test fails, please take a look at the error and update your code accordingly.
+2. **Manual human review**. In addition, your code will be manually reviewed by the project maintainers. They will assist you in improving your contribution, so please  incorporate their feedback.
+
+After the review is complete and all tests pass, your pull request will be accepted and finally merged!
+
+
+## Project Structure
+
+stdgpu is structured according to common [project layout conventions](https://api.csswg.org/bikeshed/?force=1&url=https://raw.githubusercontent.com/vector-of-bool/pitchfork/spec/data/spec.bs) which includes the following directories:
+
+- `benchmarks/stdgpu/`: The benchmarks of the library. The actual code lies in the `*.inc` files which are then included and compiled in backend-specific source files.
+- `cmake/`: Additional CMake scripts used for building and development. Backend-specific code lies in the respective subdirectories.
+- `docs/`: Directory containing the sources of this documentation. In addition, the API documentation is specified directly in the header files of the actual library.
+- `examples/`: Various example snippets, also split and compiled dependent on the chosen backend.
+- `src/stdgpu/`: Source directory of the library.
+- `tests/stdgpu/`: The unit tests of the library. Like for the benchmarks, the actual code lies in the `*.inc` files.
+- `tools/`: Optional helper scripts for development.
+
+In addition to this top-level structure, the library itself as well as the benchmarks, examples, and tests are further split into common and backend-specific code:
+
+- **Common code**: Most of the functionality works the same for any backend, so their implementation is shared between them. Library implementations are split into files with a `_detail` suffix and put into an `impl/` subdirectory. Benchmark and test implementations are put into `*.inc` files.
+- **Backend-specific code**: Some functions require calling functions of the backend, e.g. CUDA-only functions in case of the CUDA backend. These functions are put into backend directory, e.g. `src/stdgpu/cuda/`. Benchmark and test implementations are compiled in backend-specific files, e.g. `*.cu` in case of the CUDA backend.
+
+
+```{toctree}
+:hidden:
+
+contributing/coding_style
+contributing/documentation
+contributing/tests
+```

docs/development/contributing/coding_style.md

@@ -0,0 +1,63 @@
+# Coding Style
+
+We use **C++17** throughout the project. This means that you can use any features from any C++ standard up to this particular version to implement your contribution. However, more recent features cannot be directly used and should be backported, if possible, to make them accessible in the library.
+
+As one design principle of stdgpu is to closely follow the C++ standard library API, the code should obey the respective style:
+
+- Use `snake_case` for classes, functions, and variables.
+- Use `ALL_CAPS` with underscores for macros.
+- Define all symbols in the `stdgpu` namespace, prefix macros with the `STDGPU_` "namespace".
+- Move purely internal code, e.g. non-standard helper functions, into the `stdgpu::detail` namespace.
+
+Furthermore, the source code is formatted according to a modified version of the Mozilla style guide that is specified in the `.clang-format` file and enforced by **clang-format 10**. Note that other versions of clang-format, including more recent ones, may produce slightly different results which however will be considered non-conforming by our CI and, consequently, rejected.
+
+In order to check if the code is correctly formated, you can use the following command/script:
+
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake --build build --target check_code_style
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/dev/check_code_style.sh
+```
+
+:::
+
+::::
+
+
+In case the code needs to be reformatted due to non-conforming style, you can use the following command/script:
+
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake --build build --target apply_code_style
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/dev/apply_code_style.sh
+```
+
+:::
+
+::::

docs/development/contributing/documentation.md

@@ -0,0 +1,44 @@
+# Documentation
+
+We use [**Doxygen**](https://www.doxygen.org/index.html) for generating the C++ documentation and [**Sphinx**](https://www.sphinx-doc.org/) for the remaining parts. Thus, if you would like to contribute here, we recommend to do a local build of the documentation on your computer and to see how your changes will look like in the end.
+
+For building, the following tools along with their versions are required:
+
+- Doxygen **1.9.6**, which will be automatically built from source if that *exact* version is not found on your system (requires [Bison and Flex utilites](https://www.doxygen.nl/manual/install.html))
+- Sphinx including some extensions, which can all be installed by
+    ```sh
+    pip install -r docs/requirements.txt
+    ```
+
+When these documenation dependencies are installed, you can build the documentation using the following command/script:
+
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake --build build --target stdgpu_doc --parallel 8
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/dev/build_documentation.sh
+```
+
+:::
+
+::::
+
+
+:::{note}
+The `STDGPU_BUILD_DOCUMENTATION` option must be enabled for this purpose, e.g. via `-D<option>=<value>`, see [Configuration Options](../../index.md#integration).
+:::
+
+
+Afterwards, you can view the generated documentation by opening the `build/docs/html/index.html` file in your browser.

docs/development/contributing/tests.md

@@ -0,0 +1,32 @@
+# Tests
+
+We check our code by a variety of tests which complement the pre-conditions and post-conditions used throughout the library. In case you add a new class/function or you extend or provide a fix to an existing function, we recommend and encourage you to also include a corresponding unit test in the set of the existing tests.
+
+For running the unit tests, you can use the following command/script:
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake -E chdir build ctest -V -C Release
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/run_tests.sh Release
+```
+
+:::
+
+::::
+
+
+:::{note}
+The `STDGPU_BUILD_TESTS` option must be enabled to also compile the tests, which is already the default if not manually altered, see [Configuration Options](../../index.md#integration).
+:::

docs/index.md

@@ -29,3 +29,12 @@ doxygen/modules
 doxygen/annotated
 doxygen/files
 ```
+
+```{toctree}
+:hidden:
+:caption: Development
+
+development/contributing
+development/changelog
+License <https://github.com/stotko/stdgpu/blob/master/LICENSE>
+```