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")