Improve macros documentation

[cz4rs]

May 16, 2022 Documentation Bootcamp

[cz4rs]

Should we consider removing the list below (as duplicated) and only leave the link to API-Reference/Macros.md?

[ldh4]

The only concern I have about removing the list below is that there is a very subtle capitalization difference between the keywords listed on this page and the ones in API-Reference/Macros.md.
Here, it is Kokkos_ARCH_X whereas in Macros.md, it's KOKKOS_ARCH_X.
Though for CMake builds, using either doesn't seem to make any difference...

[masterleinad]

I think it's debatable whether users should be able to rely on the existence of these macros.

The CMake option always looks like Kokkos_ENABLE... (although we also define local CMake variables KOKKOS_ENABLE...) while the macro is KOKKOS_ENABLE....

[crtrott]

note I don't think that KOKKOS_ENABLE is valid from our side.

[cz4rs]

TODO:

• leave the CMake options (Kokkos_ENABLE...) and make sure they are up to date with the code
• remove KOKKOS_ENABLE_... as users should not rely on these (remove the obsolete list)
• improve the wording for KokkosCore_config.h (https://github.com/kokkos/kokkos/wiki/Compiling#41-general-information)
• make https://github.com/kokkos/kokkos/wiki/Compiling#kokkos-cmake-keyword-listing a table (improve readability)

[ajpowelsnl]

@crtrott , @masterleinad -- Just to make sure I understand the principle here, from the few comments above, I gather that you are proposing:

1. Users should not use Kokkos configuration macros, that these configuration macros are/ should be mostly / exclusively for developers (i.e., things "under the hood" in Kokkos);
2. the CMake variables, Kokkos_ENABLE_X , Kokkos_ARCH_XYZ should be the only user-facing configuration variables ?
3. CMake variables will take precedence over the configuration macros.

[ajpowelsnl]

Should we consider removing the list below (as duplicated) and only leave the link to API-Reference/Macros.md?

@cz4rs and @ldh4 -- Perhaps we could consider:

1. Making a clear delineation of what should vs. what should not be user facing (e.g., do not make configuration macros user facing, but Kokkos CMake variables should absolutely be public);
2. Removing duplicated, out-of-date / obsolete tables;
3. Provide clear explanation of what a Kokkos CMake variable is (i.e., Kokkos_ENABLE_ABC, Kokkos_ENABLE_ARCH_XYZ ) and its intended use, and clearly also state that configuration macros are not part of the public API.

[fnrizzi]

@cz4rs please update this so that you use the new sphinx branch.
All editable sources are under source/ (the wiki-md-files-to-port directory will be deleted soon).

[fnrizzi]

is this ready? if not, can you please make it draft?

Sure. How do I do that?

[cz4rs]

Converting to draft to fix conflicts and check recent changes.