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 <[email protected]> * add Cory's comments --------- Co-authored-by: Sam Wu <[email protected]>
ROCm · Aug 21, 2024 · 0562969 · 0562969
1 parent 1862031
commit 0562969
Show file tree

Hide file tree

Showing 20 changed files with 254 additions and 120 deletions.
diff --git 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
@@ -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
@@ -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`
diff --git 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(<file_name>)``. The file names, and the
-functions, variables, and macros accessible using each file are listed below.
-
-Files & Contents
-~~~~~~~~~~~~~~~~
+included by running ``include(<file_name>)``. 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 <https://github.com/ROCm/rocm-cmake>`_.
+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 <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
 
-* :ref:`genindex`
-* :ref:`search`
+You can find licensing information on the
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,5 +1,12 @@
+.. meta::
+  :description: ROCm CMake
+  :keywords: ROCm, Cmake, library, api, AMD
+
+.. _rocmdoxygendoc:
+
+****************************************************
 ROCMDoxygenDoc
-==============
+****************************************************
 
 Commands
 --------