From 3c71bb25e8bed1dbbacc01362839fd37dbf8904e Mon Sep 17 00:00:00 2001
From: Jan Stephan <jan.stephan@amd.com>
Date: Wed, 16 Jul 2025 14:10:06 +0200
Subject: [PATCH] Make initial directory and copy operations
 platform-independent

---
 docs/conf.py                | 21 ++++++++++++++-------
 docs/contribute/building.md | 22 ++++++++++++++++++++--
 2 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index dfd48d80c..d672ba3a0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,17 +9,21 @@ import shutil
 import sys
 from pathlib import Path
 
-shutil.copy2("../RELEASE.md", "./about/release-notes.md")
-shutil.copy2("../CHANGELOG.md", "./release/changelog.md")
+gh_release_path = os.path.join("..", "RELEASE.md")
+gh_changelog_path = os.path.join("..", "CHANGELOG.md")
+sphinx_release_path = os.path.join("about", "release-notes.md")
+sphinx_changelog_path = os.path.join("release", "changelog.md")
+shutil.copy2(gh_release_path, sphinx_release_path)
+shutil.copy2(gh_changelog_path, sphinx_changelog_path)
 
 # Mark the consolidated changelog as orphan to prevent Sphinx from warning about missing toctree entries
-with open("./release/changelog.md", "r+") as file:
+with open(sphinx_changelog_path, "r+", encoding="utf-8") as file:
     content = file.read()
     file.seek(0)
     file.write(":orphan:\n" + content)
 
 # Replace GitHub-style [!ADMONITION]s with Sphinx-compatible ```{admonition} blocks
-with open("./release/changelog.md", "r") as file:
+with open(sphinx_changelog_path, "r", encoding="utf-8") as file:
     lines = file.readlines()
 
     modified_lines = []
@@ -57,11 +61,14 @@ with open("./release/changelog.md", "r") as file:
 
     file.close()
 
-    with open("./release/changelog.md", 'w') as file:
+    with open(sphinx_changelog_path, "w", encoding="utf-8") as file:
         file.writelines(modified_lines)
 
-os.system("mkdir -p ../_readthedocs/html/downloads")
-os.system("cp compatibility/compatibility-matrix-historical-6.0.csv ../_readthedocs/html/downloads/compatibility-matrix-historical-6.0.csv")
+matrix_path = os.path.join("compatibility", "compatibility-matrix-historical-6.0.csv")
+rtd_path = os.path.join("..", "_readthedocs", "html", "downloads")
+if not os.path.exists(rtd_path):
+    os.makedirs(rtd_path)
+shutil.copy2(matrix_path, rtd_path)
 
 latex_engine = "xelatex"
 latex_elements = {
diff --git a/docs/contribute/building.md b/docs/contribute/building.md
index 97801832b..d4b88b071 100644
--- a/docs/contribute/building.md
+++ b/docs/contribute/building.md
@@ -28,13 +28,31 @@ See the [Python requirements file](https://github.com/ROCm/ROCm/blob/develop/doc
 
 Use the Python Virtual Environment (`venv`) and run the following commands from the project root:
 
+::::{tab-set}
+:::{tab-item} Linux and WSL
+:sync: linux
+
 ```sh
 python3 -mvenv .venv
 
-.venv/bin/python     -m pip install -r docs/sphinx/requirements.txt
-.venv/bin/python     -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
+.venv/bin/python -m pip install -r docs/sphinx/requirements.txt
+.venv/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
 ```
 
+:::
+:::{tab-item} Windows
+:sync: windows
+
+```powershell
+python -mvenv .venv
+
+.venv\Scripts\python.exe -m pip install -r docs/sphinx/requirements.txt
+.venv\Scripts\python.exe -m sphinx -T -E -b html -d _build/doctrees -D language=en docs _build/html
+```
+
+:::
+::::
+
 Navigate to `_build/html/index.html` and open this file in a web browser.
 
 ## Visual Studio Code