Apply and standardize Read the Docs documentation for HIPCC

samjwu · samjwu · commit 65d057100908 · 2023-11-08T10:52:05.000-05:00
Relates to #12 Relates to ROCm/rocm-docs-core#330 Change-Id: Ic6a67f6edb21898c2ac8cf1dce91e94c507af4ad
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/amd/hipcc/docs/sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    labels:
+      - "documentation"
+    reviewers:
+      - "samjwu"
diff --git a/amd/hipcc/.readthedocs.yaml b/amd/hipcc/.readthedocs.yaml
@@ -10,9 +10,9 @@ formats: [htmlzip, pdf, epub]
 
 python:
   install:
-  - requirements: docs/.sphinx/requirements.txt
+  - requirements: docs/sphinx/requirements.txt
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "3.8"
diff --git a/amd/hipcc/README.md b/amd/hipcc/README.md
@@ -5,39 +5,41 @@
 <!-- toc -->
 
 - [hipcc](#hipcc)
-     * [Documentation](#documentation)
-     * [Environment Variables](#envVar)
-     * [Usage](#hipcc-usage)
-     * [Building](#building)
-     * [Testing](#testing)
+  - [Documentation](#documentation)
+  - [Environment Variables](#envVar)
+  - [Usage](#usage)
+  - [Building](#building)
+  - [Testing](#testing)
 
 <!-- tocstop -->
 
 ## <a name="hipcc"></a> hipcc
 
-`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. Historically, `hipcc` was provided as a script in the HIP repo ( https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc ). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo.
+`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. Historically, `hipcc` was provided as a script in the HIP repo [https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc](https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo.
 
 `hipcc` will pass-through options to the target compiler. The tools calling hipcc must ensure the compiler options are appropriate for the target compiler.
 
 ## Documentation
 
 Run the steps below to build documentation locally.
 
-```
+```shell
 cd docs
 
-pip3 install -r .sphinx/requirements.txt
+pip3 install -r sphinx/requirements.txt
 
 python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
 ```
 
 ### <a name="envVar"></a> Environment Variables
 
 The environment variable HIP_PLATFORM may be used to specify amd/nvidia:
+
 - HIP_PLATFORM='amd' or HIP_PLATFORM='nvidia'.
 - If HIP_PLATFORM is not set, then hipcc will attempt to auto-detect based on if nvcc is found.
 
 Other environment variable controls:
+
 - HIP_PATH        : Path to HIP directory, default is one dir level above location of hipcc.
 - CUDA_PATH       : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only.
 - HSA_PATH        : Path to HSA dir (defaults to ../../hsa relative to abs_path of hipcc). Used on AMD platforms only.
diff --git a/amd/hipcc/docs/.sphinx/requirements.in b/amd/hipcc/docs/.sphinx/requirements.in
diff --git a/amd/hipcc/docs/conf.py b/amd/hipcc/docs/conf.py
@@ -4,9 +4,27 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import re
+
 from rocm_docs import ROCmDocs
 
-docs_core = ROCmDocs("HIPCC Documentation")
+with open('../CMakeLists.txt', encoding='utf-8') as f:
+    match = re.search(r'.*\bproject\(hipcc VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read())
+    if not match:
+        raise ValueError("VERSION not found!")
+    version_number = match[1]
+left_nav_title = f"HIPCC {version_number} Documentation"
+
+# for PDF output on Read the Docs
+project = "HIPCC Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
 docs_core.setup()
 
 for sphinx_var in ROCmDocs.SPHINX_VARS:
diff --git a/amd/hipcc/docs/license.md b/amd/hipcc/docs/license.md
@@ -0,0 +1,4 @@
+# License
+
+```{include} ../LICENSE.txt
+```
diff --git a/amd/hipcc/docs/sphinx/_toc.yml.in b/amd/hipcc/docs/sphinx/_toc.yml.in
@@ -8,3 +8,6 @@ subtrees:
     - file: usage
     - file: build
     - file: test
+  - caption: About
+    entries:
+    - file: license
diff --git a/amd/hipcc/docs/sphinx/requirements.in b/amd/hipcc/docs/sphinx/requirements.in
@@ -0,0 +1 @@
+rocm-docs-core==0.27.0
diff --git a/amd/hipcc/docs/sphinx/requirements.txt b/amd/hipcc/docs/sphinx/requirements.txt
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
 #    pip-compile requirements.in
@@ -92,7 +92,7 @@ requests==2.28.2
     # via
     #   pygithub
     #   sphinx
-rocm-docs-core>=0.24.0
+rocm-docs-core==0.27.0
     # via -r requirements.in
 smmap==5.0.0
     # via gitdb

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# License
++
 +```{include} ../LICENSE.txt
 +```