Enable generation of API Docs for gz-tools and sdformat (gazebosim#501)

* Enable generation of API Docs for gz-tools and sdformat
These were failing before, but it might have been because
Latex related packages were not installed.


* Do not upload unless on master
* Handle sdformat directory
* Fix upload_artifact step
---------

Signed-off-by: Addisu Z. Taddese <[email protected]>

Author: azeey

.github/workflows/nightly-upload.yml

@@ -38,16 +38,14 @@ jobs:
           required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
           use-gazebo-nightly: ${{ matrix.gazebo_distribution == 'ionic'}}
       - name: 'Add Doxygen'
-        run: sudo apt-get install -y doxygen graphviz
+        run: sudo apt-get install -y doxygen graphviz texlive-latex-extra
       - name: 'Add missing dependencies'
         run: sudo apt-get install -y libopengl-dev
       - name: 'Build Docs'
         run: |
           mkdir -p ws/src
           cd ws/src
           vcs import --input https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-${{ matrix.gazebo_distribution}}.yaml
-          rm -rf sdformat
-          rm -rf gz-tools
           sudo DEBIAN_FRONTEND=noninteractive apt-get -y install $(sort -u $(find . -iname 'packages-'${{ matrix.ubuntu_distribution}}'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | tr '\n' ' ')
           cd ..
           colcon build --merge-install --event-handlers console_cohesion+ --cmake-args -DBUILD_DOCS=ON -DBUILD_TESTING=OFF --cmake-target doc
@@ -56,6 +54,8 @@ jobs:
         with:
           name: api-docs-${{ matrix.gazebo_distribution }}
           path: ws/build/**/doxygen/html
+          if-no-files-found: 'error'
+          include-hidden-files: 'true'
 
   upload:
     name: Upload docs to production
@@ -82,7 +82,12 @@ jobs:
       with:
         name: api-docs
         path: .api-out/*
+        if-no-files-found: 'error'
+        include-hidden-files: 'true'
     - name: Commit
+      # The workflow upto this point is good for generating a preview,
+      # but only commit to deploy if we are on the master branch (not a pull request).
+      if: github.ref == 'refs/heads/master'
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}

tools/restructure_doxygen_artifacts.py

@@ -35,7 +35,8 @@
 output_dir = pathlib.Path(sys.argv[2])
 output_dir.mkdir(exist_ok=True)
 
-re_expr = R"(ignition|gz)-([a-z_]*)(\d*)"
+re_expr = R"(?:ignition|gz)-([a-z_]*)(\d*)"
+sdf_re_expr = R"(sdformat)(\d*)"
 
 
 def copy_library(lib_html, lib_name, lib_version):
@@ -47,8 +48,11 @@ def copy_library(lib_html, lib_name, lib_version):
 
 for lib in input_dir.iterdir():
     m = re.match(re_expr, lib.name)
+    if not m:
+        m = re.match(sdf_re_expr, lib.name)
+
     if m:
-        _, lib_name, lib_version = m.groups()
+        lib_name, lib_version = m.groups()
         lib_html = lib/"doxygen"/"html"
         copy_library(lib_html, lib_name, lib_version)
         # Handle gazebo->sim rename by making a copy into the sim directory