From b2523eb295fbedd5259e01067ba861fe179825ef Mon Sep 17 00:00:00 2001 From: Marcel Koch Date: Fri, 13 Sep 2024 09:40:41 +0200 Subject: [PATCH] [doc] move user-guide pages to doc --- README.md | 16 ++++++++-------- doc/index.md | 8 ++++---- .../user-guide/BENCHMARKING.md | 0 CITING.md => doc/user-guide/CITING.md | 6 ++++++ .../user-guide/CONTRIBUTING.md | 0 INSTALL.md => doc/user-guide/INSTALL.md | 11 +++++++++-- TESTING.md => doc/user-guide/TESTING.md | 2 +- doc/user-guide/benchmarking.md | 2 -- doc/user-guide/contributing.md | 2 -- doc/user-guide/publications.md | 8 -------- doc/user-guide/testing.md | 2 -- doc/user-guide/using-ginkgo.md | 9 --------- 12 files changed, 28 insertions(+), 38 deletions(-) rename BENCHMARKING.md => doc/user-guide/BENCHMARKING.md (100%) rename CITING.md => doc/user-guide/CITING.md (97%) rename CONTRIBUTING.md => doc/user-guide/CONTRIBUTING.md (100%) rename INSTALL.md => doc/user-guide/INSTALL.md (98%) rename TESTING.md => doc/user-guide/TESTING.md (99%) delete mode 100644 doc/user-guide/benchmarking.md delete mode 100644 doc/user-guide/contributing.md delete mode 100644 doc/user-guide/publications.md delete mode 100644 doc/user-guide/testing.md delete mode 100644 doc/user-guide/using-ginkgo.md diff --git a/README.md b/README.md index 25962ef7deb..2f19f28a97c 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ implemented for NVIDIA, AMD and Intel GPUs. # Prerequisites -### Linux and Mac OS +### Linux and macOS For Ginkgo core library: @@ -101,7 +101,7 @@ The Ginkgo OMP module has the following __additional__ requirements: * _MinGW_ In these environments, two problems can be encountered, the solution for which is described in the -[windows section in INSTALL.md](INSTALL.md#building-ginkgo-in-windows): +[windows section in INSTALL.md](doc/user-guide/INSTALL.md#building-ginkgo-in-windows): * `ld: error: export ordinal too large` needs the compilation flag `-O1` * `cc1plus.exe: out of memory allocating 65536 bytes` requires a modification of the environment @@ -124,7 +124,7 @@ modules depending on your machine environment (present of CUDA, ...). You can also explicitly compile with the OpenMP, CUDA, HIP or DPC++(SYCL) modules enabled to run the examples with these executors. -Please refer to the [Installation page](./INSTALL.md) for more details. +Please refer to the [Installation page](doc/user-guide/INSTALL.md) for more details. Tip: After installation, in your CMake project, Ginkgo can be added with `find_package(Ginkgo)` and the the target that is exported is `Ginkgo::ginkgo`. An example can be found in the [`test_install`](test/test_install/CMakeLists.txt). @@ -144,7 +144,7 @@ Various examples are available for you to understand and play with Ginkgo within A unique feature of Ginkgo is the ability to run benchmarks and view your results with the help of the [Ginkgo Performance Explorer (GPE)](https://ginkgo-project.github.io/gpe/). -More details about this can be found in the [BENCHMARKING.md page](./BENCHMARKING.md) +More details about this can be found in the [BENCHMARKING.md page](doc/user-guide/BENCHMARKING.md) # Bug reports and Support @@ -152,7 +152,7 @@ If you have any questions about using Ginkgo, please use [Github discussions](ht If you would like to request a feature, or have encountered a bug, please [create an issue](https://github.com/ginkgo-project/ginkgo/issues/new). Please be sure to describe your problem and provide as much information as possible. -You can also send an email to [Ginkgo's main email address](mailto:ginkgo.library@gmail.com). +You can also email [Ginkgo's main email address](mailto:ginkgo.library@gmail.com). # Licensing @@ -166,7 +166,7 @@ details. # Contributing to Ginkgo -We are glad that that you would like to contribute to Ginkgo and we are happy to help you with any questions you may have. +We are glad that you would like to contribute to Ginkgo, and we are happy to help you with any questions you may have. If you are contributing for the first time, please add yourself to the list of external contributors with the following info @@ -185,7 +185,7 @@ license, as specified in the repository's LICENSE file. #### Contribution Guidelines -When contributing to Ginkgo, to ease the review process, please follow the guidelines mentioned in [CONTRIBUTING.md](CONTRIBUTING.md). +When contributing to Ginkgo, to ease the review process, please follow the guidelines mentioned in [CONTRIBUTING.md](doc/user-guide/CONTRIBUTING.md). It also contains other general recommendations such as writing proper commit messages, understanding Ginkgo's library design, relevant C++ information etc. @@ -216,4 +216,4 @@ pages = {2:1--2:33} ``` For more information on topical subjects, please refer to the [CITING.md -page](CITING.md). +page](doc/user-guide/CITING.md). diff --git a/doc/index.md b/doc/index.md index a69c0d5196f..f311fef9481 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,7 +1,7 @@ # User Guide This is the main page for the Ginkgo library user documentation. The repository is hosted on [github](https://github.com/ginkgo-project/ginkgo). -Documentation on aspects such as the build system, can be found at the [install page](user-guide/using-ginkgo.md). +Documentation on aspects such as the build system, can be found at the [install page](user-guide/INSTALL.md). The {doxy}`Examples` can help you get started with using Ginkgo. The Ginkgo library can be grouped into modules which form the basic building blocks of Ginkgo. The modules can be summarized as follows: @@ -24,9 +24,9 @@ The Ginkgo library can be grouped into modules which form the basic building blo Tutorial Examples <_doxygen/html/Examples.html#https://> -Publications -user-guide/contributing -Using Ginkgo +Publications +user-guide/CONTRIBUTING +Using Ginkgo API <_doxygen/html/index.html#https://> ::: diff --git a/BENCHMARKING.md b/doc/user-guide/BENCHMARKING.md similarity index 100% rename from BENCHMARKING.md rename to doc/user-guide/BENCHMARKING.md diff --git a/CITING.md b/doc/user-guide/CITING.md similarity index 97% rename from CITING.md rename to doc/user-guide/CITING.md index 45418c09d87..c2e32ed6119 100644 --- a/CITING.md +++ b/doc/user-guide/CITING.md @@ -131,3 +131,9 @@ keywords = {irregular matrices, GPUs, Sparse Matrix Vector Product (SpMV)} primaryClass={cs.MS} } ``` + +:::{toctree} +self +Ginkgo White Paper +Slides and Outreach +::: \ No newline at end of file diff --git a/CONTRIBUTING.md b/doc/user-guide/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to doc/user-guide/CONTRIBUTING.md diff --git a/INSTALL.md b/doc/user-guide/INSTALL.md similarity index 98% rename from INSTALL.md rename to doc/user-guide/INSTALL.md index 3ef19a3dfc2..2f11843dcbe 100644 --- a/INSTALL.md +++ b/doc/user-guide/INSTALL.md @@ -126,7 +126,7 @@ Additionally, the following CMake options have effect on the build process: For example, to build everything (in debug mode), use: -```cmake +```bash cmake .. -BDebug -DCMAKE_BUILD_TYPE=Debug -DGINKGO_DEVEL_TOOLS=ON \ -DGINKGO_BUILD_TESTS=ON -DGINKGO_BUILD_REFERENCE=ON -DGINKGO_BUILD_OMP=ON \ -DGINKGO_BUILD_CUDA=ON -DGINKGO_BUILD_HIP=ON @@ -246,4 +246,11 @@ user, e.g. when installing Ginkgo system-wide, it might be necessary to prefix the call with `sudo`. After the installation, CMake can find ginkgo with `find_package(Ginkgo)`. -An example can be found in the [`test_install`](test/test_install/CMakeLists.txt). +An example can be found in the [`test_install`](../../test/test_install/CMakeLists.txt). + +:::{toctree} +:hidden: +self +TESTING +BENCHMARKING +::: diff --git a/TESTING.md b/doc/user-guide/TESTING.md similarity index 99% rename from TESTING.md rename to doc/user-guide/TESTING.md index 9c523ff9b69..065355d40a4 100644 --- a/TESTING.md +++ b/doc/user-guide/TESTING.md @@ -13,7 +13,7 @@ make test The output should contain several lines of the form: -``` +```text Start 1: path/to/test 1/13 Test #1: path/to/test ............................. Passed 0.01 sec ``` diff --git a/doc/user-guide/benchmarking.md b/doc/user-guide/benchmarking.md deleted file mode 100644 index b9bbe844e70..00000000000 --- a/doc/user-guide/benchmarking.md +++ /dev/null @@ -1,2 +0,0 @@ -:::{include} ../../BENCHMARKING.md -::: \ No newline at end of file diff --git a/doc/user-guide/contributing.md b/doc/user-guide/contributing.md deleted file mode 100644 index 7bbeceaa7d3..00000000000 --- a/doc/user-guide/contributing.md +++ /dev/null @@ -1,2 +0,0 @@ -:::{include} ../../CONTRIBUTING.md -::: \ No newline at end of file diff --git a/doc/user-guide/publications.md b/doc/user-guide/publications.md deleted file mode 100644 index 85b9066bf63..00000000000 --- a/doc/user-guide/publications.md +++ /dev/null @@ -1,8 +0,0 @@ -:::{include} ../../CITING.md -::: - -:::{toctree} -self -Ginkgo White Paper -Slides and Outreach -::: \ No newline at end of file diff --git a/doc/user-guide/testing.md b/doc/user-guide/testing.md deleted file mode 100644 index b129992a559..00000000000 --- a/doc/user-guide/testing.md +++ /dev/null @@ -1,2 +0,0 @@ -:::{include} ../../TESTING.md -::: \ No newline at end of file diff --git a/doc/user-guide/using-ginkgo.md b/doc/user-guide/using-ginkgo.md deleted file mode 100644 index 9b33ae62d19..00000000000 --- a/doc/user-guide/using-ginkgo.md +++ /dev/null @@ -1,9 +0,0 @@ -:::{include} ../../INSTALL.md -::: - -:::{toctree} -:hidden: -self -testing -benchmarking -::: \ No newline at end of file