Move docs content into a separate dir

and update the script to work outside of scripts dir.

Author: lukaszstolarczuk

.github/workflows/docs.yml

@@ -41,13 +41,15 @@ jobs:
       run: echo "$HOME/.local/bin" >> $GITHUB_PATH
 
     - name: Build the documentation
-      working-directory: scripts
-      run: python3 generate_docs.py
+      run: |
+        mkdir build
+        cd build
+        python3 ../docs/generate_docs.py
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8 # v3.0.0
       with:
-        path: docs/html
+        path: build/docs_build/generated/html
 
   deploy:
     name: Deploy docs to GitHub Pages

.github/workflows/reusable_docs_build.yml

@@ -30,5 +30,7 @@ jobs:
         python3 -m pip install -r third_party/requirements.txt
 
     - name: Build the documentation
-      working-directory: scripts
-      run: python3 generate_docs.py
+      run: |
+        mkdir build
+        cd build
+        python3 ../docs/generate_docs.py

.gitignore

@@ -58,7 +58,7 @@ __pycache__/
 *.py[cod]
 
 # Generated docs
-docs/
+docs_build/
 
 # Build files
 /build*/

RELEASE_STEPS.md

@@ -41,7 +41,7 @@ Do changes for a release:
   - For major releases mention API and ABI compatibility with the previous release
 - Update project's version in a few places:
   - For major and minor releases: `UMF_VERSION_CURRENT` in `include/umf/base.h` (the API version)
-  - `release` variable in `scripts/docs_config/conf.py` (for docs)
+  - `release` variable in `docs/config/conf.py` (for docs)
   - `UMF_VERSION` variable in `.github/workflows/reusable_basic.yml` (for installation test)
 - For major releases update ABI version in `.map` and `.def` files
   - These files are defined for all public libraries (`libumf` and `proxy_lib`, at the moment)

docs/README.md

@@ -0,0 +1,8 @@
+To generate HTML documentation run the `generate_docs.py` script from the `build` dir.
+It will create extra `./docs_build` directory, where the intermediate and final files
+will be created. HTML docs will be in the `./docs_build/generated/html` directory.
+
+The script requires:
+ * [Doxygen](http://www.doxygen.nl/) at least v1.9.1
+ * [Python](https://www.python.org/downloads/) at least v3.8
+ * and python pip requirements, as defined in `third_party/requirements.txt`

scripts/assets/images/intro_architecture.png renamed to docs/assets/images/intro_architecture.png

@@ -2058,7 +2058,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = ../docs/xml
+XML_OUTPUT             = docs_build/doxyxml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

scripts/docs_config/Doxyfile renamed to docs/config/Doxyfile

@@ -49,7 +49,9 @@
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for breathe extension -------------------------------------------
-breathe_projects = {project: "../../docs/xml"}
+# 'doxyxml' dir is generated with Doxygen; it's supposed to be in a directory
+# one above the config directory.
+breathe_projects = {project: "../doxyxml"}
 breathe_default_project = project
 breathe_show_include = False
 breathe_default_members = ("members", "undoc-members")

scripts/docs_config/api.rst renamed to docs/config/api.rst

@@ -6,17 +6,20 @@
 """
 
 from pathlib import Path
-from shutil import rmtree
+from shutil import rmtree, copytree
 import subprocess  # nosec B404
 import time
 
 
 def _check_cwd() -> None:
-    script_path = Path(__file__).resolve().parent
     cwd = Path.cwd()
-    if script_path != cwd:
+    include_dir = Path(cwd, "../include")
+    # Verify if include dir is one level up (as defined in Doxyfile)
+    if not include_dir.exists():
         print(
-            f"{__file__} script has to be run from the 'scripts' directory. Terminating..."
+            f"Include directory {include_dir.resolve()} not found! "
+            "Please run this script from <repo_root_dir>/build!",
+            flush=True,
         )
         exit(1)
 
@@ -66,8 +69,17 @@ def _generate_html(config_path: Path, docs_path: Path) -> None:
 
 def main() -> None:
     _check_cwd()
-    config_path = Path("docs_config").resolve()
-    docs_path = Path("..", "docs").resolve()
+
+    script_dir = Path(__file__).resolve().parent
+    docs_build_path = Path("docs_build").resolve()
+
+    # Sphinx and breathe require access to a Doxygen generated dir ('doxyxml')
+    # so we copy the whole content of the 'docs' dir to the build dir.
+    copytree(Path(script_dir), docs_build_path, dirs_exist_ok=True)
+
+    config_path = Path(docs_build_path, "config").resolve()
+    docs_path = Path(docs_build_path, "generated").resolve()
+
     start = time.time()
     _prepare_docs_dir(docs_path)
     _generate_xml(config_path, docs_path)