Initial port of documentation to rocm-docs-core

lawruble13 · Aug 18, 2023 · 98b7bcc · 98b7bcc
1 parent 189d497
commit 98b7bcc
Show file tree

Hide file tree

Showing 23 changed files with 76 additions and 51 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 .vs*/**/*
-build/**/*
+build/**/*
+docs/_build/**/*
+docs/.sphinx/_toc.yml
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -40,5 +40,4 @@ add_custom_target(format COMMAND cmake-format -i ${CMAKE_FILES} WORKING_DIRECTOR
 enable_testing()
 add_custom_target(check COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure -C ${CMAKE_CFG_INTDIR})
 add_subdirectory(test)
-add_subdirectory(doc)
-
+add_subdirectory(docs)
diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,42 @@
+# Variables of the form ${<variable>} are substituted, currently the following
+# list is supported:
+#   - ${branch} (or {branch}) the name of the current branch
+#   - ${url} (or {url}) github url of the current project
+#   - ${project:<project_name>} base url of the documentation of <project_name>
+#     based on intersphinx_mapping.
+# These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
+root: src/index.rst
+subtrees:
+  - caption: Basic Common Functionality
+    entries:
+      - file: src/ROCMCheckTargetIds.rst
+      - file: src/ROCMSetupVersion.rst
+      - file: src/ROCMAnalyzers.rst
+  - caption: Installation & Packaging
+    entries:
+      - file: src/ROCMInstallTargets.rst
+        subtrees:
+          - entries:
+            - file: src/ROCMInstallSymlinks.rst
+            - file: src/ROCMHeaderWrapper.rst
+      - file: src/ROCMCreatePackage.rst
+        subtrees:
+          - entries:
+            - file: src/ROCMClients.rst
+            - file: src/ROCMPackageConfigHelpers.rst
+  - caption: Standard Tooling
+    entries:
+      - file: src/ROCMClangTidy.rst
+      - file: src/ROCMCppCheck.rst
+      - file: src/ROCMTest.rst
+  - caption: Documentation in CMake
+    entries:
+      - file: src/ROCMDocs.rst
+      - file: src/ROCMDoxygenDoc.rst
+      - file: src/ROCMSphinxDoc.rst
+  - caption: Internal usage
+    entries:
+      - file: src/ROCMUtilities.rst
diff --git a/doc/CMakeLists.txt → docs/CMakeLists.txt b/doc/CMakeLists.txt → docs/CMakeLists.txt
diff --git a/doc/src/conf.py → docs/conf.py b/doc/src/conf.py → docs/conf.py
@@ -14,12 +14,17 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+setting_all_article_info = True
+
+# TODO: remove this for cross-linking with other projects using intersphinx
+external_projects_remote_repository = ""
+
+external_projects_current_project = "ROCmCMakeBuildTools"
+
 
 # -- Project information -----------------------------------------------------
 
-project = 'rocm-cmake'
-copyright = '2021, Paul Fultz II'
-author = 'Paul Fultz II'
+project = 'ROCmCMakeBuildTools'
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,7 +33,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.moderncmakedomain'
+    'sphinxcontrib.moderncmakedomain',
+    "rocm_docs"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -44,30 +50,10 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'default'
-html_theme_options = {
-    'footerbgcolor':    '#00182d',
-    'footertextcolor':  '#ffffff',
-    'sidebarbgcolor':   '#e4ece8',
-    'sidebarbtncolor':  '#00a94f',
-    'sidebartextcolor': '#333333',
-    'sidebarlinkcolor': '#00a94f',
-    'relbarbgcolor':    '#00529b',
-    'relbartextcolor':  '#ffffff',
-    'relbarlinkcolor':  '#ffffff',
-    'bgcolor':          '#ffffff',
-    'textcolor':        '#444444',
-    'headbgcolor':      '#f2f2f2',
-    'headtextcolor':    '#003564',
-    'headlinkcolor':    '#3d8ff2',
-    'linkcolor':        '#2b63a8',
-    'visitedlinkcolor': '#2b63a8',
-    'codebgcolor':      '#eeeeee',
-    'codetextcolor':    '#333333',
-}
+
+html_theme = 'rocm_docs_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']
diff --git a/doc/requirements.txt → docs/requirements.txt b/doc/requirements.txt → docs/requirements.txt
@@ -1,2 +1,3 @@
 sphinx==4.1.2
 sphinxcontrib-moderncmakedomain==3.19
+rocm-docs-core==0.2.0
diff --git a/doc/src/ROCMAnalyzers.rst → docs/src/ROCMAnalyzers.rst b/doc/src/ROCMAnalyzers.rst → docs/src/ROCMAnalyzers.rst
@@ -20,5 +20,3 @@ 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.
-
-
diff --git a/doc/src/ROCMCheckTargetIds.rst → docs/src/ROCMCheckTargetIds.rst b/doc/src/ROCMCheckTargetIds.rst → docs/src/ROCMCheckTargetIds.rst
diff --git a/doc/src/ROCMClangTidy.rst → docs/src/ROCMClangTidy.rst b/doc/src/ROCMClangTidy.rst → docs/src/ROCMClangTidy.rst
diff --git a/doc/src/ROCMClients.rst → docs/src/ROCMClients.rst b/doc/src/ROCMClients.rst → docs/src/ROCMClients.rst
@@ -4,7 +4,7 @@ ROCMClients
 Commands
 --------
 
-.. cmake::command:: rocm_package_setup_client_component
+.. cmake:command:: rocm_package_setup_client_component
 
 .. code-block:: cmake
 
@@ -21,4 +21,3 @@ Commands
     )
 
 Setup a client component for packaging. See ``rocm_package_setup_component``.
-
diff --git a/doc/src/ROCMCppCheck.rst → docs/src/ROCMCppCheck.rst b/doc/src/ROCMCppCheck.rst → docs/src/ROCMCppCheck.rst
diff --git a/doc/src/ROCMCreatePackage.rst → docs/src/ROCMCreatePackage.rst b/doc/src/ROCMCreatePackage.rst → docs/src/ROCMCreatePackage.rst
diff --git a/doc/src/ROCMDocs.rst → docs/src/ROCMDocs.rst b/doc/src/ROCMDocs.rst → docs/src/ROCMDocs.rst
diff --git a/doc/src/ROCMDoxygenDoc.rst → docs/src/ROCMDoxygenDoc.rst b/doc/src/ROCMDoxygenDoc.rst → docs/src/ROCMDoxygenDoc.rst
diff --git a/doc/src/ROCMHeaderWrapper.rst → docs/src/ROCMHeaderWrapper.rst b/doc/src/ROCMHeaderWrapper.rst → docs/src/ROCMHeaderWrapper.rst
@@ -4,7 +4,7 @@ ROCMHeaderWrapper
 Commands
 --------
 
-.. cmake::command:: rocm_wrap_header_file
+.. cmake:command:: rocm_wrap_header_file
 
 .. code-block:: cmake
 
@@ -39,9 +39,9 @@ Guards
 A guard item consists of the guard string ``<guard>``, a wrapper location ``<wrapper-location>``, and an output location ``<output-location>``.
 You may specify any number of guard strings, wrapper locations and output locations.
 Guard items will be created from the arguments, and if necessary the following defaults will be used:
- - Default ``<guard>``: ``WRAPPER``
- - Default ``<wrapper-location>``: ``${CMAKE_PROJECT_NAME}/include``
- - Default ``<output-location>``: The associated ``<wrapper-location>``
+* Default ``<guard>``: ``WRAPPER``
+* Default ``<wrapper-location>``: ``${CMAKE_PROJECT_NAME}/include``
+* Default ``<output-location>``: The associated ``<wrapper-location>``
 If no guard items are specified, one will be created using all of the default values.
 Each guard item will create a wrapper file at ``${PROJECT_BINARY_DIR}/<output-location>/<header-file>`` for each header file.
 This wrapper file will have the include guard ``ROCM_<guard>_<item-path>``, where ``<item-path>`` is ``<header-file>`` with each ``/`` and ``.`` replaced with ``_``.
@@ -78,7 +78,7 @@ If the name of the wrapper file being generated is the same as the name of any `
 but it does allow projects which search for specific strings inside a header file to function correctly.
 
 
-.. cmake::command:: rocm_wrap_header_dir
+.. cmake:command:: rocm_wrap_header_dir
 
 .. code-block:: cmake
 

diff --git a/doc/src/ROCMInstallSymlinks.rst → docs/src/ROCMInstallSymlinks.rst b/doc/src/ROCMInstallSymlinks.rst → docs/src/ROCMInstallSymlinks.rst
diff --git a/doc/src/ROCMInstallTargets.rst → docs/src/ROCMInstallTargets.rst b/doc/src/ROCMInstallTargets.rst → docs/src/ROCMInstallTargets.rst
@@ -8,12 +8,12 @@ Commands
 
 .. code-block:: cmake
 
-    rocm_install(TARGETS <target>... [...])
-    rocm_install({FILES | PROGRAMS} <file>... [...])
-    rocm_install(DIRECTORY <dir>... [...])
-    rocm_install(SCRIPT <file> [...])
-    rocm_install(CODE <code> [...])
-    rocm_install(EXPORT <export-name> [...])
+    rocm_install(TARGETS <target>... [<arg>...])
+    rocm_install(<FILES | PROGRAMS> <file>... [<arg>...])
+    rocm_install(DIRECTORY <dir>... [<arg>...])
+    rocm_install(SCRIPT <file> [<arg>...])
+    rocm_install(CODE <code> [<arg>...])
+    rocm_install(EXPORT <export-name> [<arg>...])
 
 Wraps installers to install to the correct component (devel or runtime) unless COMPONENT is specified. The TARGETS signature wraps ``rocm_install_targets``, all other signatures wrap ``install``.
 
@@ -48,4 +48,3 @@ Install targets into the appropriate directory. Unless COMPONENT is specified, l
     )
 
 Export the installed targets so they can be consumed with ``find_package``.
-
diff --git a/doc/src/ROCMPackageConfigHelpers.rst → docs/src/ROCMPackageConfigHelpers.rst b/doc/src/ROCMPackageConfigHelpers.rst → docs/src/ROCMPackageConfigHelpers.rst
diff --git a/doc/src/ROCMSetupVersion.rst → docs/src/ROCMSetupVersion.rst b/doc/src/ROCMSetupVersion.rst → docs/src/ROCMSetupVersion.rst
diff --git a/doc/src/ROCMSphinxDoc.rst → docs/src/ROCMSphinxDoc.rst b/doc/src/ROCMSphinxDoc.rst → docs/src/ROCMSphinxDoc.rst
@@ -4,7 +4,7 @@ ROCMSphinxDoc
 Commands
 --------
 
-.. cmake:command:: rocm_add_doxygen_doc
+.. cmake:command:: rocm_add_sphinx_doc
 
 .. code-block:: cmake
 

diff --git a/doc/src/ROCMTest.rst → docs/src/ROCMTest.rst b/doc/src/ROCMTest.rst → docs/src/ROCMTest.rst
diff --git a/doc/src/ROCMUtilities.rst → docs/src/ROCMUtilities.rst b/doc/src/ROCMUtilities.rst → docs/src/ROCMUtilities.rst
@@ -4,23 +4,23 @@ ROCMUtilities
 Commands
 --------
 
-.. cmake::command:: rocm_join_if_set
+.. cmake:command:: rocm_join_if_set
 
 .. code-block:: cmake
 
     rocm_join_if_set(<glue> <inout_var> [<input>...])
 
 Join all the ``<input>`` arguments together using the ``<glue>`` string. If ``<inout_var>`` names a variable with a set value, join that string at the beginning, also using the ``<glue>`` string, and always store the result in ``<inout_var>``.
 
-.. cmake::command:: rocm_defer
+.. cmake:command:: rocm_defer
 
 .. code-block:: cmake
 
     rocm_defer(<command>)
 
 Call ``<command>`` at the end of configure.
 
-.. cmake::command:: rocm_find_program_version
+.. cmake:command:: rocm_find_program_version
 
 .. code-block:: cmake
 
@@ -39,4 +39,3 @@ Determine the presence and installed version of a program that accepts the ``--v
 Optionally check the version using any of the comparison operators (each comparison operator may only be specified once).
 If ``out-var`` is not specified, it defaults to ``<PROGRAM>_VERSION``.
 If the program is found, ``<out-var>`` is set to the version detected. If that version satisfies all version constraints, the variable ``<out-var>_OK`` is set to ``TRUE``, otherwise it is set to ``FALSE``.
-
diff --git a/doc/src/index.rst → docs/src/index.rst b/doc/src/index.rst → docs/src/index.rst