From 8e17a75353dff08e5711d53cb022e5a9d0c9ad0b Mon Sep 17 00:00:00 2001
From: Sam Wu <sam.wu2@amd.com>
Date: Mon, 15 Jan 2024 09:26:18 -0700
Subject: [PATCH] Standardize documentation for ReadtheDocs (#1027)

[ROCm/rccl commit: 246dbd16d7233b6dcb318a805a44a81a90baeaf4]
---
 projects/rccl/.gitignore                   | 10 ----------
 projects/rccl/docs/.gitignore              |  5 +++++
 projects/rccl/docs/conf.py                 | 17 ++++++++++++-----
 projects/rccl/docs/doxygen/Doxyfile        |  2 +-
 projects/rccl/docs/license.rst             |  4 ++++
 projects/rccl/docs/sphinx/_toc.yml.in      |  4 +++-
 projects/rccl/docs/sphinx/requirements.in  |  2 +-
 projects/rccl/docs/sphinx/requirements.txt |  4 +---
 8 files changed, 27 insertions(+), 21 deletions(-)
 create mode 100644 projects/rccl/docs/.gitignore
 create mode 100644 projects/rccl/docs/license.rst

diff --git a/projects/rccl/.gitignore b/projects/rccl/.gitignore
index 919c9dffb8..7accae00d6 100644
--- a/projects/rccl/.gitignore
+++ b/projects/rccl/.gitignore
@@ -1,13 +1,3 @@
 # Copyright (c) 2015-2016, NVIDIA CORPORATION. All rights reserved.
 *.gcov
 /coverage/
-
-# documentation artifacts
-build/
-_build/
-_images/
-_static/
-_templates/
-_toc.yml
-docBin/
-_doxygen/
diff --git a/projects/rccl/docs/.gitignore b/projects/rccl/docs/.gitignore
new file mode 100644
index 0000000000..1356dbd287
--- /dev/null
+++ b/projects/rccl/docs/.gitignore
@@ -0,0 +1,5 @@
+_build/
+_doxygen/
+doxygen/html
+doxygen/xml
+sphinx/_toc.yml
diff --git a/projects/rccl/docs/conf.py b/projects/rccl/docs/conf.py
index 09a41d7f43..efa311f3a1 100644
--- a/projects/rccl/docs/conf.py
+++ b/projects/rccl/docs/conf.py
@@ -8,9 +8,6 @@ import subprocess
 
 from rocm_docs import ROCmDocs
 
-
-external_projects_current_project = "rccl"
-
 name = "RCCL"
 get_major = r'sed -n -e "s/^NCCL_MAJOR.*\([0-9]\+\).*/\1/p" ../makefiles/version.mk'
 get_minor = r'sed -n -e "s/^NCCL_MINOR.*\([0-9]\{2,\}\).*/\1/p" ../makefiles/version.mk'
@@ -18,12 +15,22 @@ get_patch = r'sed -n -e "s/^NCCL_PATCH.*\([0-9]\+\).*/\1/p" ../makefiles/version
 major = subprocess.getoutput(get_major)
 minor = subprocess.getoutput(get_minor)
 patch = subprocess.getoutput(get_patch)
+version_number = f"{major}.{minor}.{patch}"
+
+# for PDF output on Read the Docs
+project = f"{name} Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
 
 external_toc_path = "./sphinx/_toc.yml"
 
-docs_core = ROCmDocs(f"{name} {major}.{minor}.{patch} Documentation")
-docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/docBin/xml")
+docs_core = ROCmDocs(f"{name} {version_number} Documentation")
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
 docs_core.setup()
 
+external_projects_current_project = "rccl"
+
 for sphinx_var in ROCmDocs.SPHINX_VARS:
     globals()[sphinx_var] = getattr(docs_core, sphinx_var)
diff --git a/projects/rccl/docs/doxygen/Doxyfile b/projects/rccl/docs/doxygen/Doxyfile
index b2c1bdf4f0..792b88fc74 100644
--- a/projects/rccl/docs/doxygen/Doxyfile
+++ b/projects/rccl/docs/doxygen/Doxyfile
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docBin
+OUTPUT_DIRECTORY       = .
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
diff --git a/projects/rccl/docs/license.rst b/projects/rccl/docs/license.rst
new file mode 100644
index 0000000000..60fbe85948
--- /dev/null
+++ b/projects/rccl/docs/license.rst
@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE.txt
diff --git a/projects/rccl/docs/sphinx/_toc.yml.in b/projects/rccl/docs/sphinx/_toc.yml.in
index 731cc40627..55cfb98019 100644
--- a/projects/rccl/docs/sphinx/_toc.yml.in
+++ b/projects/rccl/docs/sphinx/_toc.yml.in
@@ -4,5 +4,7 @@ subtrees:
   - file: api
   - file: allapi
   - file: attributions
-
+- caption: About
+  entries:
+  - file: license
 
diff --git a/projects/rccl/docs/sphinx/requirements.in b/projects/rccl/docs/sphinx/requirements.in
index 313c5e9418..b80af26188 100644
--- a/projects/rccl/docs/sphinx/requirements.in
+++ b/projects/rccl/docs/sphinx/requirements.in
@@ -1 +1 @@
-rocm-docs-core>=0.24.0
+rocm-docs-core==0.30.3
diff --git a/projects/rccl/docs/sphinx/requirements.txt b/projects/rccl/docs/sphinx/requirements.txt
index 279bb23e11..b991dc0070 100644
--- a/projects/rccl/docs/sphinx/requirements.txt
+++ b/projects/rccl/docs/sphinx/requirements.txt
@@ -84,9 +84,7 @@ pygments==2.15.0
     #   pydata-sphinx-theme
     #   sphinx
 pyjwt[crypto]==2.6.0
-    # via
-    #   pygithub
-    #   pyjwt
+    # via pygithub
 pynacl==1.5.0
     # via pygithub
 pytz==2023.3.post1