Documentation - Doxygen documentation for on Read the Docs output and other documentation standardization

.github/dependabot.yml

@@ -6,13 +6,13 @@
 version: 2
 updates:
   - package-ecosystem: "pip" # See documentation for possible values
-    directory: "/docs/.sphinx" # Location of package manifests
+    directory: "/docs/sphinx" # Location of package manifests
     open-pull-requests-limit: 10
     schedule:
       interval: "daily"
     labels:
-      - "dependencies"
-      - "noCI"
       - "documentation"
+      - "dependencies"
+      - "ci:docs-only"
     reviewers:
       - "samjwu"

.github/workflows/linting.yml

@@ -0,0 +1,12 @@
+name: Linting
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+
+jobs:
+  call-workflow-passing-data:
+    name: Documentation
+    uses: RadeonOpenCompute/rocm-docs-core/.github/workflows/linting.yml@develop

.readthedocs.yaml

@@ -6,9 +6,15 @@ version: 2
 sphinx:
    configuration: docs/conf.py
 
-formats: [htmlzip]
+formats: [htmlzip, pdf, epub]
 
 python:
-   version: "3.8"
    install:
-   - requirements: docs/.sphinx/requirements.txt
+   - requirements: docs/sphinx/requirements.txt
+
+build:
+   os: ubuntu-20.04
+   tools:
+      python: "3.8"
+   apt_packages:
+     - "doxygen"

README.md

@@ -8,9 +8,10 @@ For more details, go to [docs](docs) page.
 ## Documentation
 
 Run the steps below to build documentation locally.
-```
+
+```bash
 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
 ```
 

docs/conf.py

@@ -26,13 +26,33 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import re
+
 from rocm_docs import ROCmDocs
 
 
-external_projects_current_project = "rocal"
+with open('../CMakeLists.txt', encoding='utf-8') as f:
+    match = re.search(r'.*\bset\(VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read())
+    if not match:
+        raise ValueError("VERSION not found!")
+    version_number = match[1]
+left_nav_title = f"rocAL {version_number} Documentation"
+
+# for PDF output on Read the Docs
+project = "rocAL Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
 
-docs_core = ROCmDocs("rocAL Documentation")
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
+docs_core.enable_api_reference()
 docs_core.setup()
 
+external_projects_current_project = "rocal"
+
 for sphinx_var in ROCmDocs.SPHINX_VARS:
     globals()[sphinx_var] = getattr(docs_core, sphinx_var)

docs/doxygen/.gitignore

@@ -0,0 +1,3 @@
+html
+latex
+xml