From 0562969c774f4021a75dbea5fc438433525f488e Mon Sep 17 00:00:00 2001 From: randyh62 <42045079+randyh62@users.noreply.github.com> Date: Wed, 21 Aug 2024 11:45:06 -0700 Subject: [PATCH] Reorg docs621 (#224) * doc reorg with src folder (#195) * doc reorg with src folder * leo's comments * added Files and Content * Update codeowners for docs * reorg based on Paul's feedback --------- Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> * add Cory's comments --------- Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> --- .github/CODEOWNERS | 3 +- docs/src/_toc.yml.in | 26 ++-- docs/src/contents.rst | 85 +++++++++++++ docs/src/index.rst | 112 ++++-------------- docs/src/reference/ROCMAnalyzers.rst | 13 +- docs/src/reference/ROCMCheckTargetIds.rst | 9 +- docs/src/reference/ROCMClangTidy.rst | 9 +- docs/src/reference/ROCMClients.rst | 9 +- docs/src/reference/ROCMCppCheck.rst | 9 +- docs/src/reference/ROCMCreatePackage.rst | 9 +- docs/src/reference/ROCMDocs.rst | 9 +- docs/src/reference/ROCMDoxygenDoc.rst | 9 +- docs/src/reference/ROCMHeaderWrapper.rst | 9 +- docs/src/reference/ROCMInstallSymlinks.rst | 9 +- docs/src/reference/ROCMInstallTargets.rst | 9 +- .../reference/ROCMPackageConfigHelpers.rst | 9 +- docs/src/reference/ROCMSetupVersion.rst | 9 +- docs/src/reference/ROCMSphinxDoc.rst | 9 +- docs/src/reference/ROCMTest.rst | 9 +- docs/src/reference/ROCMUtilities.rst | 9 +- 20 files changed, 254 insertions(+), 120 deletions(-) create mode 100644 docs/src/contents.rst diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 380ece0f..ce4d4faf 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,5 +1,6 @@ * @pfultz2 @lawruble13 @cgmb # Documentation files -docs/* @ROCm/rocm-documentation @pfultz2 @lawruble13 @cgmb +docs/ @ROCm/rocm-documentation @pfultz2 @lawruble13 @cgmb *.md @ROCm/rocm-documentation @pfultz2 @lawruble13 @cgmb *.rst @ROCm/rocm-documentation @pfultz2 @lawruble13 @cgmb +.readthedocs.yaml @ROCm/rocm-documentation @pfultz2 @lawruble13 @cgmb diff --git a/docs/src/_toc.yml.in b/docs/src/_toc.yml.in index 23256060..173a83e0 100644 --- a/docs/src/_toc.yml.in +++ b/docs/src/_toc.yml.in @@ -10,24 +10,20 @@ defaults: maxdepth: 6 root: index.rst subtrees: - - caption: Basic Common Functionality + - caption: Installation + entries: + - file: reference/ROCMInstallTargets.rst + - file: reference/ROCMInstallSymlinks.rst + - file: reference/ROCMHeaderWrapper.rst + - file: reference/ROCMCreatePackage.rst + - file: reference/ROCMClients.rst + - file: reference/ROCMPackageConfigHelpers.rst + - caption: Basic functions entries: - file: reference/ROCMCheckTargetIds.rst - file: reference/ROCMSetupVersion.rst - file: reference/ROCMAnalyzers.rst - - caption: Installation & Packaging - entries: - - file: reference/ROCMInstallTargets.rst - subtrees: - - entries: - - file: reference/ROCMInstallSymlinks.rst - - file: reference/ROCMHeaderWrapper.rst - - file: reference/ROCMCreatePackage.rst - subtrees: - - entries: - - file: reference/ROCMClients.rst - - file: reference/ROCMPackageConfigHelpers.rst - - caption: Standard Tooling + - caption: Standard tooling entries: - file: reference/ROCMClangTidy.rst - file: reference/ROCMCppCheck.rst @@ -37,7 +33,7 @@ subtrees: - file: reference/ROCMDocs.rst - file: reference/ROCMDoxygenDoc.rst - file: reference/ROCMSphinxDoc.rst - - caption: Internal usage + - caption: Internal use entries: - file: reference/ROCMUtilities.rst - caption: About diff --git a/docs/src/contents.rst b/docs/src/contents.rst new file mode 100644 index 00000000..e040b2b6 --- /dev/null +++ b/docs/src/contents.rst @@ -0,0 +1,85 @@ +.. rocm-cmake documentation master file, created by + sphinx-quickstart on Thu Sep 16 18:46:06 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. +.. highlight:: cmake + +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _contents: + +**************************************************** +Modules and functions +**************************************************** + +- :ref:`rocmanalyzers` + + :any:`rocm_mark_as_analyzer` + + :any:`ROCM_ENABLE_GH_ANNOTATIONS` +- :ref:`rocmchecktargetids` + + :any:`rocm_check_target_ids` +- :ref:`rocmclangtidy` + + :any:`rocm_enable_clang_tidy` + + :any:`rocm_clang_tidy_check` + + :any:`CLANG_TIDY_EXE` + + :any:`CLANG_TIDY_CACHE` + + :any:`CLANG_TIDY_CACHE_SIZE` + + :any:`CLANG_TIDY_DEPEND_ON_TARGET` +- :ref:`rocmclients` + + :any:`rocm_package_setup_client_component` +- :ref:`rocmcppcheck` + + :any:`rocm_enable_cppcheck` + + :any:`CPPCHECK_EXE` + + :any:`CPPCHECK_BUILD_DIR` +- :ref:`rocmcreatepackage` + + :any:`rocm_create_package` + + :any:`rocm_package_add_rpm_dependencies` + + :any:`rocm_package_add_deb_dependencies` + + :any:`rocm_package_add_dependencies` + + :any:`rocm_package_setup_component` +- :ref:`rocmdocs` + + :any:`rocm_mark_as_doc` + + :any:`rocm_clean_doc_output` +- :ref:`rocmdoxygendoc` + + :any:`rocm_add_doxygen_doc` + + :any:`DOXYGEN_EXECUTABLE` + + :any:`DOT_EXECUTABLE` +- :ref:`rocminstallsymlinks` + + :any:`rocm_install_symlink_subdir` +- :ref:`rocminstalltargets` + + :any:`rocm_install` + + :any:`rocm_install_targets` + + :any:`rocm_export_targets` +- :ref:`rocmconfighelpers` + + :any:`rocm_configure_package_config_file` +- :ref:`rocmsetupversion` + + :any:`rocm_get_version` + + :any:`rocm_setup_version` +- :ref:`rocmsphinxdoc` + + :any:`rocm_add_doxygen_doc` + + :any:`SPHINX_EXECUTABLE` + + :any:`SPHINX_${BUILDER}_DIR` +- :ref:`rocmtest` + + :any:`rocm_enable_test_package` + + :any:`rocm_add_test` + + :any:`rocm_add_test_executable` + + :any:`rocm_test_header` + + :any:`rocm_test_headers` + + :any:`rocm_install_test` + + :any:`rocm_mark_as_test` + + :any:`rocm_link_test_dependencies` + + :any:`rocm_test_link_libraries` + + :any:`CTEST_PARALLEL_LEVEL` + + :any:`CTEST_TIMEOUT` + + :any:`ROCM_TEST_GDB` +- :ref:`rocmutilities` + + :any:`rocm_join_if_set` + + :any:`rocm_defer` + + :any:`rocm_find_program_version` + +Index and tables +================ + +* :ref:`genindex` +* :ref:`search` \ No newline at end of file diff --git a/docs/src/index.rst b/docs/src/index.rst index 7bf69845..38fde880 100755 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -4,103 +4,43 @@ contain the root `toctree` directive. .. highlight:: cmake -ROCm CMake Build Tools -====================== +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD -Summary -------- +.. _rocm-cmake: -ROCm CMake Build Tools (also stylized as "ROCmCMakeBuildTools" and previously -known as "rocm-cmake") is a collection of functions that unify and simplify the -CMake code of the ROCm components, as well as ensuring consistency across these -components. +**************************************************** +ROCm CMake build tools +**************************************************** -Usage ------ +ROCm CMake build tools (also known as "rocm-cmake") is a collection of functions +that unify and simplify the CMake code of ROCm components, as well as ensuring +consistency across these different components. The ROCm CMake build tools are used +when building and developing many AMD ROCm libraries, but are not runtime dependencies +for any libraries, packages or executables. -The ROCm CMake Build Tools are primarily used at build time of a library, and -as such are not runtime dependencies for any generated libraries, packages, -or executables. +.. important:: + ROCm CMake tools are not required when building or compiling an application that uses ROCm or HIP components. -The tools can be included into a CMake project by running:: +The build tools can be included into a CMake project by running: + +.. code-block:: shell find_package(ROCmCMakeBuildTools) # or find_package(ROCM) # deprecated, but included for backwards compatibility Once the tools have been included in this manner, individual files may be -included by running ``include()``. The file names, and the -functions, variables, and macros accessible using each file are listed below. - -Files & Contents -~~~~~~~~~~~~~~~~ +included by running ``include()``. The file names, the +functions, variables, and macros accessible using each file are described in +this documentation. -- :any:`ROCMAnalyzers` - + :any:`rocm_mark_as_analyzer` - + :any:`ROCM_ENABLE_GH_ANNOTATIONS` -- :any:`ROCMCheckTargetIds` - + :any:`rocm_check_target_ids` -- :any:`ROCMClangTidy` - + :any:`rocm_enable_clang_tidy` - + :any:`rocm_clang_tidy_check` - + :any:`CLANG_TIDY_EXE` - + :any:`CLANG_TIDY_CACHE` - + :any:`CLANG_TIDY_CACHE_SIZE` - + :any:`CLANG_TIDY_DEPEND_ON_TARGET` -- :any:`ROCMClients` - + :any:`rocm_package_setup_client_component` -- :any:`ROCMCppCheck` - + :any:`rocm_enable_cppcheck` - + :any:`CPPCHECK_EXE` - + :any:`CPPCHECK_BUILD_DIR` -- :any:`ROCMCreatePackage` - + :any:`rocm_create_package` - + :any:`rocm_package_add_rpm_dependencies` - + :any:`rocm_package_add_deb_dependencies` - + :any:`rocm_package_add_dependencies` - + :any:`rocm_package_setup_component` -- :any:`ROCMDocs` - + :any:`rocm_mark_as_doc` - + :any:`rocm_clean_doc_output` -- :any:`ROCMDoxygenDoc` - + :any:`rocm_add_doxygen_doc` - + :any:`DOXYGEN_EXECUTABLE` - + :any:`DOT_EXECUTABLE` -- :any:`ROCMInstallSymlinks` - + :any:`rocm_install_symlink_subdir` -- :any:`ROCMInstallTargets` - + :any:`rocm_install` - + :any:`rocm_install_targets` - + :any:`rocm_export_targets` -- :any:`ROCMPackageConfigHelpers` - + :any:`rocm_configure_package_config_file` -- :any:`ROCMSetupVersion` - + :any:`rocm_get_version` - + :any:`rocm_setup_version` -- :any:`ROCMSphinxDoc` - + :any:`rocm_add_doxygen_doc` - + :any:`SPHINX_EXECUTABLE` - + :any:`SPHINX_${BUILDER}_DIR` -- :any:`ROCMTest` - + :any:`rocm_enable_test_package` - + :any:`rocm_add_test` - + :any:`rocm_add_test_executable` - + :any:`rocm_test_header` - + :any:`rocm_test_headers` - + :any:`rocm_install_test` - + :any:`rocm_mark_as_test` - + :any:`rocm_link_test_dependencies` - + :any:`rocm_test_link_libraries` - + :any:`CTEST_PARALLEL_LEVEL` - + :any:`CTEST_TIMEOUT` - + :any:`ROCM_TEST_GDB` -- :any:`ROCMUtilities` - + :any:`rocm_join_if_set` - + :any:`rocm_defer` - + :any:`rocm_find_program_version` +You can access the build tools on the `ROCm CMake GitHub repository `_. +For a complete listing of the features of ROCm CMake refer to :ref:`contents`. -Indices and tables -================== +To contribute to the documentation, refer to +`Contributing to ROCm `_. -* :ref:`genindex` -* :ref:`search` +You can find licensing information on the +`Licensing `_ page. diff --git a/docs/src/reference/ROCMAnalyzers.rst b/docs/src/reference/ROCMAnalyzers.rst index 1a91471d..213045f4 100755 --- a/docs/src/reference/ROCMAnalyzers.rst +++ b/docs/src/reference/ROCMAnalyzers.rst @@ -1,7 +1,14 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmanalyzers: + +**************************************************** ROCMAnalyzers -============= +**************************************************** -This creates a ``analyze`` target which can run all analysis for a project. +This creates an ``analyze`` target which can run all analysis for a project. Commands -------- @@ -19,4 +26,4 @@ Variables .. cmake:variable:: ROCM_ENABLE_GH_ANNOTATIONS -Set this variable to ``ON`` so that analyzers will emit diagnostics in a format that github can use to annotate pull requests. +Set this variable to ``ON`` so that analyzers will emit diagnostics in a format that GitHub can use to annotate pull requests. diff --git a/docs/src/reference/ROCMCheckTargetIds.rst b/docs/src/reference/ROCMCheckTargetIds.rst index 386f60f4..49dcbaa5 100755 --- a/docs/src/reference/ROCMCheckTargetIds.rst +++ b/docs/src/reference/ROCMCheckTargetIds.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmchecktargetids: + +**************************************************** ROCMCheckTargetIds -================== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMClangTidy.rst b/docs/src/reference/ROCMClangTidy.rst index 22024e26..6363a7b4 100755 --- a/docs/src/reference/ROCMClangTidy.rst +++ b/docs/src/reference/ROCMClangTidy.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmclangtidy: + +**************************************************** ROCMClangTidy -============= +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMClients.rst b/docs/src/reference/ROCMClients.rst index 9384e8d1..8a2914b0 100644 --- a/docs/src/reference/ROCMClients.rst +++ b/docs/src/reference/ROCMClients.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmclients: + +**************************************************** ROCMClients -=========== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMCppCheck.rst b/docs/src/reference/ROCMCppCheck.rst index 610b7eb1..d892bd23 100755 --- a/docs/src/reference/ROCMCppCheck.rst +++ b/docs/src/reference/ROCMCppCheck.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmcppcheck: + +**************************************************** ROCMCppCheck -============ +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMCreatePackage.rst b/docs/src/reference/ROCMCreatePackage.rst index 5ca4fd58..e980ebfc 100755 --- a/docs/src/reference/ROCMCreatePackage.rst +++ b/docs/src/reference/ROCMCreatePackage.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmcreatepackage: + +**************************************************** ROCMCreatePackage -================= +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMDocs.rst b/docs/src/reference/ROCMDocs.rst index 057c6c5f..e4c04599 100755 --- a/docs/src/reference/ROCMDocs.rst +++ b/docs/src/reference/ROCMDocs.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmdocs: + +**************************************************** ROCMDocs -======== +**************************************************** This creates a ``doc`` target which can run all documentation generation for the project. diff --git a/docs/src/reference/ROCMDoxygenDoc.rst b/docs/src/reference/ROCMDoxygenDoc.rst index 929808f6..52064f95 100755 --- a/docs/src/reference/ROCMDoxygenDoc.rst +++ b/docs/src/reference/ROCMDoxygenDoc.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmdoxygendoc: + +**************************************************** ROCMDoxygenDoc -============== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMHeaderWrapper.rst b/docs/src/reference/ROCMHeaderWrapper.rst index 665f0b9a..181273f5 100644 --- a/docs/src/reference/ROCMHeaderWrapper.rst +++ b/docs/src/reference/ROCMHeaderWrapper.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmheaderwrapper: + +**************************************************** ROCMHeaderWrapper -================= +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMInstallSymlinks.rst b/docs/src/reference/ROCMInstallSymlinks.rst index 78e529b9..70d226e7 100644 --- a/docs/src/reference/ROCMInstallSymlinks.rst +++ b/docs/src/reference/ROCMInstallSymlinks.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocminstallsymlinks: + +**************************************************** ROCMInstallSymlinks -=================== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMInstallTargets.rst b/docs/src/reference/ROCMInstallTargets.rst index bf296a96..35678a71 100644 --- a/docs/src/reference/ROCMInstallTargets.rst +++ b/docs/src/reference/ROCMInstallTargets.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocminstalltargets: + +**************************************************** ROCMInstallTargets -================== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMPackageConfigHelpers.rst b/docs/src/reference/ROCMPackageConfigHelpers.rst index bf89dc9d..b53ff761 100755 --- a/docs/src/reference/ROCMPackageConfigHelpers.rst +++ b/docs/src/reference/ROCMPackageConfigHelpers.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmconfighelpers: + +**************************************************** ROCMPackageConfigHelpers -======================== +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMSetupVersion.rst b/docs/src/reference/ROCMSetupVersion.rst index de5b43a3..9d75cf17 100644 --- a/docs/src/reference/ROCMSetupVersion.rst +++ b/docs/src/reference/ROCMSetupVersion.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmSetupVersion: + +**************************************************** ROCMSetupVersion -================ +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMSphinxDoc.rst b/docs/src/reference/ROCMSphinxDoc.rst index 4fb8cfab..e17b42d0 100755 --- a/docs/src/reference/ROCMSphinxDoc.rst +++ b/docs/src/reference/ROCMSphinxDoc.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmSphinxDoc: + +**************************************************** ROCMSphinxDoc -============= +**************************************************** Commands -------- diff --git a/docs/src/reference/ROCMTest.rst b/docs/src/reference/ROCMTest.rst index abeaa18d..4c01f3ca 100644 --- a/docs/src/reference/ROCMTest.rst +++ b/docs/src/reference/ROCMTest.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmtest: + +**************************************************** ROCMTest -======== +**************************************************** This adds a ``check`` target to build and run the tests using CTest. A ``tests`` target can be used to just build the tests. All the tests are then packaged in the test component. diff --git a/docs/src/reference/ROCMUtilities.rst b/docs/src/reference/ROCMUtilities.rst index ebd8bf33..72861ba1 100644 --- a/docs/src/reference/ROCMUtilities.rst +++ b/docs/src/reference/ROCMUtilities.rst @@ -1,5 +1,12 @@ +.. meta:: + :description: ROCm CMake + :keywords: ROCm, Cmake, library, api, AMD + +.. _rocmutilities: + +**************************************************** ROCMUtilities -============= +**************************************************** Commands --------