Update documentation to match ROCm (#142)

Co-authored-by: Sam Wu <[email protected]>

.github/dependabot.yml

@@ -0,0 +1,17 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    labels:
+      - "documentation"
+      - "dependencies"
+      - "ci:docs-only"
+    reviewers:
+      - "samjwu"

.github/workflows/test.yml

@@ -56,7 +56,7 @@ jobs:
       run: |
         python -m pip install --upgrade setuptools pip wheel
         python -m pip install cget ninja
-        python -m pip install -r doc/requirements.txt
+        python -m pip install -r docs/requirements.txt
         python -m pip install -r test/docsphinx/docs/.sphinx/requirements.txt
     - name: Install Doxygen
       uses: ssciwr/doxygen-install@v1
@@ -69,4 +69,3 @@ jobs:
         cget build -T doc
         cget build -Cy --test -DROCM_CMAKE_GENERATOR=Ninja
         cget build -T doc
-

.gitignore

@@ -1,2 +1,4 @@
 .vs*/**/*
-build/**/*
+build/**/*
+docs/_build/
+docs/sphinx/_toc.yml

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+  configuration: docs/src/conf.py
+
+formats: [htmlzip, pdf, epub]
+
+python:
+  install:
+  - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"

CMakeLists.txt

@@ -43,4 +43,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)

README.md

@@ -1,5 +1,4 @@
-rocm-cmake
-==================
+# rocm-cmake
 
 rocm-cmake is a collection of CMake modules for common build and development
 tasks within the ROCm project. It is therefore a build dependency for many of
@@ -10,8 +9,10 @@ it is required for building some of the libraries that are _a part of_ ROCm.
 
 To install from source, run:
 
-    mkdir build
-    cd build
-    cmake ..
-    cmake --build .
-    sudo cmake --build . --target install
+```bash
+mkdir build
+cd build
+cmake ..
+cmake --build .
+sudo cmake --build . --target install
+```

docs/CMakeLists.txt

@@ -0,0 +1,5 @@
+include(ROCMSphinxDoc)
+rocm_add_sphinx_doc(${CMAKE_CURRENT_LIST_DIR}/src
+    BUILDER html
+    OUTPUT_DIR html
+)

doc/requirements.txt → docs/requirements.in

@@ -1,2 +1,2 @@
-sphinx==4.1.2
-sphinxcontrib-moderncmakedomain==3.19
+sphinxcontrib-moderncmakedomain==3.19
+rocm-docs-core==0.31.0

docs/requirements.txt

@@ -0,0 +1,163 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+accessible-pygments==0.0.4
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.14.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.3
+    # via pydata-sphinx-theme
+breathe==4.35.0
+    # via rocm-docs-core
+certifi==2023.11.17
+    # via requests
+cffi==1.16.0
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via sphinx-external-toc
+cryptography==41.0.7
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.19.1
+    # via rocm-docs-core
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.41
+    # via rocm-docs-core
+idna==3.6
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==7.0.1
+    # via sphinx
+importlib-resources==6.1.1
+    # via rocm-docs-core
+jinja2==3.1.3
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.3
+    # via jinja2
+mdit-py-plugins==0.3.5
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==1.0.0
+    # via rocm-docs-core
+packaging==23.2
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pycparser==2.21
+    # via cffi
+pydata-sphinx-theme==0.14.4
+    # via
+    #   rocm-docs-core
+    #   sphinx-book-theme
+pygithub==2.1.1
+    # via rocm-docs-core
+pygments==2.17.2
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.8.0
+    # via
+    #   pygithub
+    #   pyjwt
+pynacl==1.5.0
+    # via pygithub
+python-dateutil==2.8.2
+    # via pygithub
+pytz==2023.3.post1
+    # via babel
+pyyaml==6.0.1
+    # via
+    #   myst-parser
+    #   rocm-docs-core
+    #   sphinx-external-toc
+requests==2.31.0
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core==0.31.0
+    # via -r requirements.in
+six==1.16.0
+    # via python-dateutil
+smmap==5.0.1
+    # via gitdb
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==5.3.0
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   rocm-docs-core
+    #   sphinx-book-theme
+    #   sphinx-copybutton
+    #   sphinx-design
+    #   sphinx-external-toc
+    #   sphinx-notfound-page
+sphinx-book-theme==1.0.1
+    # via rocm-docs-core
+sphinx-copybutton==0.5.2
+    # via rocm-docs-core
+sphinx-design==0.5.0
+    # via rocm-docs-core
+sphinx-external-toc==0.3.1
+    # via rocm-docs-core
+sphinx-notfound-page==1.0.0
+    # via rocm-docs-core
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-moderncmakedomain==3.19
+    # via -r requirements.in
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+typing-extensions==4.9.0
+    # via
+    #   pydata-sphinx-theme
+    #   pygithub
+urllib3==2.1.0
+    # via
+    #   pygithub
+    #   requests
+wrapt==1.16.0
+    # via deprecated
+zipp==3.17.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources

docs/src/_toc.yml.in

@@ -0,0 +1,45 @@
+# 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: index.rst
+subtrees:
+  - caption: Basic Common Functionality
+    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
+    entries:
+      - file: reference/ROCMClangTidy.rst
+      - file: reference/ROCMCppCheck.rst
+      - file: reference/ROCMTest.rst
+  - caption: Documentation in CMake
+    entries:
+      - file: reference/ROCMDocs.rst
+      - file: reference/ROCMDoxygenDoc.rst
+      - file: reference/ROCMSphinxDoc.rst
+  - caption: Internal usage
+    entries:
+      - file: reference/ROCMUtilities.rst
+  - caption: About
+    entries:
+      - file: license.rst