cexa-project/kokkos-cheat-sheet

Cheat sheets for the HPC C++ library Kokkos

kokkos-cheat-sheet's Issues

How to use Kokkos installed with CMake from an old Makefile project

Make the cheat sheet more API-oriented

For now (i.e. when finalizing #19), the cheat sheet has a style which is not fully descriptive of the API, unlike the OpenMP cheat sheet or the SYCL cheat sheet.

Signatures of functions are incomplete and do not explicit input parameter types. By instance, the signature for a View is:

Kokkos::View<DataType, LayoutType, MemorySpace, MemoryTraits> view("label", numberOfElements);

while in the API doc, the signature is displayed as (without descriptive text):

template <class DataType [, class LayoutType] [, class MemorySpace] [, class MemoryTraits]>
class View;

View()

View(const View<DT, Prop...> &rhs)

View(View &&rhs)

View(const std::string &name, const IntType&... indices)

View(const std::string &name, const array_layout &layout)

View(const AllocProperties &prop, const IntType&... indices)

View(const AllocProperties &prop, const array_layout &layout)

View(pointer_type ptr, const IntType&... indices)

View(pointer_type ptr, const array_layout &layout)

View(const ScratchSpace &space, const IntType&... indices)

View(const ScratchSpace &space, const array_layout &layout)

View(const View<DT, Prop...> &rhs, Args... args)

Obviously, not all signatures should be in the cheat sheet, but we could include the most common ones. The types of the input parameters are explicited, which would be an improvement.

Move to a different print format?

Currently, Markdown files are converted to $\LaTeX$ to obtain a printable PDF file. This approach was quick to setup, but has its own limitations. We don't have a fine control on how elements are displayed in the flow of text. Automatic spacing between elements is tedious while neither tables nor code blocks can break between columns or pages. Maybe $\LaTeX$ isn't flexible enough for our needs.

Maybe we should use a different intermediate language, such as EPUB? This format is used for digital books and is based on HTML and CSS. Generating EPUB files with Pandoc is already feasible. The code examples may be highlighted by a JS library. Some nice CSS3 features such as column-count would give the same feel and taste as the current approach. Bonus point, we would have the web and the print version simultaneously!

This is not a burning topic, but is something to consider if we continue to improve the cheat sheet.

Use CMake for build

For now, the project has one source file. Since we will to have more, it would be interesting to manage the build with CMake. Question is, is it worth it?

Add a persona of a young / mid-carreer physicist that rewrites a kokkos code from scratch

Add the instal cheat sheet to our website

Describe our typical users

Choose what version number strategy to use

We can either use our own version number (0.1.0, 1.0.0, etc.), or stick to Kokkos version number (4.2.0). The former gives us full control over it, the later gives a strong hint that the documentation is tied to a specific version of Kokkos. Problem is, what if we have our own patches to apply? Maybe we can keep the tweak version number for our own needs:

4.2.0.1
^ ^ ^ ^
| | | + Cheat sheet version
| | +-- Kokkos patch version
| +---- Kokkos minor version
+------ Kokkos major version

Rename the repo to comply with the Linux Fundation rules

For instance, Cheat Sheet for Kokkos.

Add a persona for system engineer handling mostly CI/installation

Add license

Automatic deployment with actions

As proposed in #6, using #8, automatically generating the pdf should be great.

Create Docker image for easy build