[skip-ci] [docu] Generate Doxygen docs with Makefile + GitHub Actions 3

.github/workflows/root-docs.yml

@@ -0,0 +1,288 @@
+name: 'ROOT Docs'
+
+on:
+  # https://github.com/root-project/root/pull/12112#issuecomment-1411004278
+  pull_request:
+    branches:
+      - '**'
+    paths-ignore:
+      - 'doc/**'
+      - 'documentation/**'
+
+  # Allows nightly builds to trigger one run for each branch easily, by
+  # providing the relevant branch as "default" value here:
+  workflow_call:
+    inputs:
+      head_ref:
+        type: string
+        default: master
+      base_ref:
+        type: string
+        default: master
+      ref_name:
+        type: string
+        default: master
+
+  workflow_dispatch:
+    inputs:
+      head_ref:
+        description: rebase from ...
+        type: string
+        required: true
+        default: master
+      base_ref:
+        description: ... to ... (can have same value)
+        type: string
+        required: true
+        default: master
+      incremental:
+        description: 'Do incremental build'
+        type: boolean
+        required: true
+        default: true
+      binaries:
+        description: Create binary packages and upload them as artifacts
+        type: boolean
+        required: true
+        default: false
+      buildtype:
+        description: The CMAKE_BUILD_TYPE to use for non-Windows.
+        type: choice
+        options:
+        - Debug
+        - RelWithDebInfo
+        - Release
+        - MinSizeRel
+        default: Debug
+        required: true
+      docu_input: # TODO: overwrite makeinput.sh with these args
+        description: Folders to build documentation for. All folders are built if empty.
+        type: string
+        default: ""
+        required: false
+
+jobs:
+  build-docs:
+    runs-on:
+      - self-hosted
+      - linux
+      - x64
+
+    env:
+      PLATFORM: alma9
+      DOC_DIR: rootdoc
+      DOC_LOCATION: /github/home
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+
+    permissions:
+      contents: read
+
+    container:
+      image: registry.cern.ch/root-ci/alma9:buildready # ALSO UPDATE BELOW!
+      options: '--security-opt label=disable --rm --name rootdoc' # ALSO UPDATE BELOW!
+      env:
+        OS_APPLICATION_CREDENTIAL_ID: '7f5b64a265244623a3a933308569bdba'
+        OS_APPLICATION_CREDENTIAL_SECRET: ${{ secrets.OS_APPLICATION_CREDENTIAL_SECRET }}
+        OS_AUTH_TYPE: 'v3applicationcredential'
+        OS_AUTH_URL: 'https://keystone.cern.ch/v3'
+        OS_IDENTITY_API_VERSION: 3
+        OS_INTERFACE: 'public'
+        OS_REGION_NAME: 'cern'
+        PYTHONUNBUFFERED: true
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python Virtual Env
+      # if the `if` expr is false, `if` still has exit code 0.
+      # if the `if` block is entered, the block's exit code becomes the exit
+      # code of the `if`.
+      run: 'if [ -d /py-venv/ROOT-CI/bin/ ]; then . /py-venv/ROOT-CI/bin/activate && echo PATH=$PATH >> $GITHUB_ENV; fi'
+
+    # TODO: install latest versions in image on root-ci-images
+    - name: Install Doxygen 1.10.0
+      run : |
+        mkdir -p ${{ github.workspace }}/doxygen
+        curl -L https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.linux.bin.tar.gz | tar -xz -C ${{ github.workspace }}/doxygen/ --strip-components=1
+        echo PATH=$PATH:${{ github.workspace }}/doxygen/bin >> $GITHUB_ENV
+
+    - name: Install qhelpgenerator-qt5
+      run: |
+        dnf update -y
+        dnf upgrade -y
+        dnf install -y qt5-doctools
+        which qhelpgenerator-qt5
+
+    - name: Apply option overrides
+      if: ${{ github.event_name != 'schedule' }}
+      env:
+        OVERRIDES: "testing=off roottest=off minimal=on" # can be removed if this workflow is merged with root-ci.yml
+        CONFIGFILE: '.github/workflows/root-ci-config/buildconfig/alma9.txt'
+      shell: bash
+      run: |
+        set -x
+        echo '' >> "$CONFIGFILE"
+        for ENTRY in $OVERRIDES; do
+            KEY=$( echo "$ENTRY" | cut -d '=' -f 1 )
+            # Add entry to file if not exists, otherwise replace
+            if grep -q "$KEY=" "$CONFIGFILE"; then
+                sed -i "s/$KEY=.*\$/$ENTRY/" "$CONFIGFILE"
+            else
+                echo "$ENTRY" >> "$CONFIGFILE"
+            fi
+        done
+        cat "$CONFIGFILE" || true
+
+    - name: Dump GitHub context
+      env:
+        GITHUB_CONTEXT: ${{ toJSON(github) }}
+      run: echo "$GITHUB_CONTEXT"
+
+
+    - name: Print debug info
+      run:  'printf "%s@%s\\n" "$(whoami)" "$(hostname)";
+              ls -la
+            '
+
+    - name: Pull Request Build
+      if: github.event_name == 'pull_request'
+      env:
+        INCREMENTAL: ${{ !contains(github.event.pull_request.labels.*.name, 'clean build') }}
+        GITHUB_PR_ORIGIN: ${{ github.event.pull_request.head.repo.clone_url }}
+      run: ".github/workflows/root-ci-config/build_root.py
+                        --buildtype       Release
+                        --platform        alma9
+                        --dockeropts      '--security-opt label=disable --rm'
+                        --incremental     $INCREMENTAL
+                        --base_ref        ${{ github.base_ref }}
+                        --sha             ${{ github.sha }}
+                        --pull_repository ${{ github.event.pull_request.head.repo.clone_url }}
+                        --head_ref        refs/pull/${{ github.event.pull_request.number }}/head:${{ github.event.pull_request.head.ref }}
+                        --head_sha        ${{ github.event.pull_request.head.sha }}
+                        --repository      ${{ github.server_url }}/${{ github.repository }}
+                  "
+    # - name: Nightly build
+    #   if:   github.event_name == 'schedule'
+    #   run: ".github/workflows/root-ci-config/build_root.py
+    #               --buildtype      Release
+    #               --platform       alma9
+    #               --incremental    false
+    #               --binaries       false
+    #               --base_ref       ${{ inputs.ref_name }}
+    #               --repository     ${{ github.server_url }}/${{ github.repository }}
+    #         "
+
+#     - name: Workflow dispatch
+#       if:   github.event_name == 'workflow_dispatch'
+#       run: ".github/workflows/root-ci-config/build_root.py
+#                   --buildtype      Release
+#                   --platform       alma9
+#                   --incremental    ${{ inputs.incremental }}
+#                   --base_ref       ${{ inputs.base_ref }}
+#                   --head_ref       ${{ inputs.head_ref }}
+#                   --binaries       ${{ inputs.binaries }}
+#                   --repository     ${{ github.server_url }}/${{ github.repository }}
+#            "
+
+    - name: Run Doxygen
+      shell: bash
+      run: |
+              source ${DOC_LOCATION}/ROOT-CI/build/bin/thisroot.sh
+              export DOXYGEN_OUTPUT_DIRECTORY=${DOC_LOCATION}/${DOC_DIR}_TMP
+
+              cd ${DOC_LOCATION}/ROOT-CI/src/documentation/doxygen
+              make -j `nproc --all`
+
+              if [ -d "${DOC_LOCATION}/${DOC_DIR}/html" ]; then
+                rm -rf "${DOC_LOCATION}/${DOC_DIR}/html"
+              fi
+              mv -f ${DOXYGEN_OUTPUT_DIRECTORY}/html ${DOC_LOCATION}/${DOC_DIR}
+
+              if [ -d ${DOC_LOCATION}/${DOC_DIR}/notebooks ]; then
+                rm -rf "${DOC_LOCATION}/${DOC_DIR}/notebooks"
+              fi
+              mv -f ${DOXYGEN_OUTPUT_DIRECTORY}/notebooks ${DOC_LOCATION}/${DOC_DIR}
+
+    - name: Create documentation archives
+      working-directory: ${{ env.DOC_LOCATION }}
+      shell: bash
+      run: |
+        tarname=${DOC_DIR}.tar
+        tar cf $tarname ${DOC_DIR}
+
+    #Upload to GitHub as an artifact (optional)
+    - name: Upload tar file
+      if:   ${{ !cancelled() }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: rootdoc.tar
+        path: ${{env.DOC_LOCATION}}/${{env.DOC_DIR}}.tar
+        if-no-files-found: error
+
+    # Install AWS CLI before syncing to S3
+    - name: Install AWS CLI
+      run: |
+        python -m pip install --upgrade pip
+        pip install awscli
+        aws configure set default.s3.max_concurrent_requests 200
+        aws configure list
+
+    - name: Sync to S3
+      run: |
+        pwd
+        ls -l ${DOC_LOCATION}
+        aws --endpoint-url https://s3.cern.ch s3 sync --delete ${DOC_LOCATION}/rootdoc_TMP s3://root/doc-test/
+      env:
+        AWS_ACCESS_KEY_ID: ${{ secrets.WS_ACCESS_KEY_ID_WEB }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_WEB }}
+        AWS_REGION: "eu-west-1"
+        AWS_ENDPOINT_URL: https://s3.cern.ch/
+
+    # DEST="s3://root/99999_${PR_NUMBER:-}" # if PR, upload in s3://root/99999_<prnumber>
+    # aws --endpoint-url https://s3.cern.ch s3 sync --delete build/99999_${PR_NUMBER:-} ${DEST}
+
+    # OpenStack upload works somehow like this
+    # - name: Install OpenStack CLI
+    #   run: |
+    #     dnf install -y python3-openstackclient
+    #     pip install --upgrade openstacksdk
+
+    # - name: Upload Documentation to OpenStack Swift
+    #   run: |
+    #     openstack container create rootdoc
+    #     openstack object create rootdoc ${{env.DOC_LOCATION}}/${{env.DOC_DIR}} --recursive
+
+    # - name: Update deployment status (success)
+    #   if: success()
+    #   uses: chrnorm/deployment-status@releases/v1
+    #   with:
+    #     token: ${{ secrets.GITHUB_TOKEN }}
+    #     target_url: https://adrianduesselberg/rootdoc/index.html  # Replace with the actual URL
+    #     state: 'success'
+    #     deployment_id: ${{ steps.test.outputs.deployment_id }}
+
+    # - name: Sync HTML to the server
+    #   shell: bash
+    #   run: |
+    #     docdir=${{env.DOC_DIR}}
+
+    #     # Check if the docdir contains 'html'
+    #     if [[ "$docdir" == *html* ]]; then
+    #       rsync --delete -a $docdir/ root.cern.ch:/var/www/root/root/$docdir
+    #       ret=$?
+    #     else
+    #       rsync --delete --exclude release-notes.html -a $docdir/ root.cern.ch:/var/www/root/doc/$docdir
+    #       ret=$?
+    #     fi
+
+    #     # upload the archives if necessary
+    #     if [[ "$docdir" != "master" && "$docdir" != "html602" ]]; then
+    #       scp $tarnamegz root.cern.ch:/var/www/root/download/
+    #       scp $tarnamexz2 root.cern.ch:/var/www/root/download/
+    #     fi
+
+    #     # Exit with the return status of the rsync command
+    #     exit $ret

documentation/doxygen/Doxyfile

@@ -1594,7 +1594,7 @@ SITEMAP_URL            =
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_QHP           = YES
+GENERATE_QHP           = NO
 
 # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify
 # the file name of the resulting .qch file. The path specified is relative to
@@ -1649,7 +1649,7 @@ QHP_SECT_FILTER_ATTRS  =
 # run qhelpgenerator on the generated .qhp file.
 # This tag requires that the tag GENERATE_QHP is set to YES.
 
-QHG_LOCATION           = qhelpgenerator
+QHG_LOCATION           = qhelpgenerator-qt5
 
 # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be
 # generated, together with the HTML files, they form an Eclipse help plugin. To

documentation/doxygen/DoxygenLayout.xml

@@ -1,10 +1,10 @@
 <doxygenlayout version="1.0">
-  <!-- Generated by doxygen 1.8.6 -->
+  <!-- First version generated by doxygen 1.8.6 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title=""/>
     <tab type="user" visible="yes" title="Tutorials" url="group__Tutorials.html"/>
-    <tab type="modules" visible="yes" title="Functional Parts" intro=""/>
+    <tab type="topics" visible="yes" title="Functional Parts" intro=""/>
     <tab type="namespaces" visible="yes" title="">
       <tab type="namespacelist" visible="yes" title="" intro=""/>
       <tab type="namespacemembers" visible="yes" title="" intro=""/>

documentation/doxygen/Makefile

@@ -65,7 +65,6 @@ doxygen: filter pyzdoc
 	doxygen
 	bash ./CleanNamespaces.sh
 	gzip $(DOXYGEN_IMAGE_PATH)/ROOT.tag
-	gzip $(DOXYGEN_IMAGE_PATH)/ROOT.qch
 	rm -rf files c1* *.ps *.eps *.png *.jpg *.tex *.svg *.pdf *.root *.xpm *.out *.dat *.dtd *.dot *.txt *.csv *.log *.rs
 	rm -rf listofclass.sh tmva* data* result* config* test* Roo* My* Freq*
 	rm -f Doxyfile_INPUT filter htmlfooter.html MDF.C pca.C

documentation/doxygen/filter.cxx

@@ -81,7 +81,9 @@
 #include <stdarg.h>
 #include <memory>
 
-using std::string, std::ios_base, std::unique_ptr;
+using std::string;
+using std::ios_base;
+using std::unique_ptr;
 
 // Auxiliary functions
 void   FilterClass();

documentation/doxygen/makeinput.sh

@@ -8,6 +8,11 @@
 # This line is mandatory. Do not comment it
 echo "INPUT = ./mainpage.md                    \\" > Doxyfile_INPUT
 
+# Add to the list of files to be analyzed the .pyzdoc files created by extract_docstrings.py
+# and print_roofit_pyz_doctrings.py
+ls $DOXYGEN_PYZDOC_PATH/*.pyzdoc | sed -e "s/$/ \\\\/"  \
+>> Doxyfile_INPUT
+
 echo "        ../../core/base/                 \\" >> Doxyfile_INPUT
 echo "        ../../core/dictgen/              \\" >> Doxyfile_INPUT
 echo "        ../../core/cont/                 \\" >> Doxyfile_INPUT
@@ -70,6 +75,7 @@ echo "        ../../sql/                       \\" >> Doxyfile_INPUT
 echo "        ../../tutorials/                 \\" >> Doxyfile_INPUT
 echo "        ../../bindings/tpython/          \\" >> Doxyfile_INPUT
 echo "        ../../bindings/pyroot/           \\" >> Doxyfile_INPUT
+echo "        ../../bindings/pyroot/pythonizations/python/ROOT/_pythonization/__init__.py          \\" >> Doxyfile_INPUT
 echo "        ../../bindings/r/                \\" >> Doxyfile_INPUT
 
 # echo "        ../../core/clib/                 \\" >> Doxyfile_INPUT
@@ -83,9 +89,3 @@ echo "        ../../bindings/r/                \\" >> Doxyfile_INPUT
 # echo "        ../../net/rootd/                 \\" >> Doxyfile_INPUT
 # echo "        ../../net/rpdutils/              \\" >> Doxyfile_INPUT
 
-
-# Add to the list of files to be analyzed the .pyzdoc files created by extract_docstrings.py
-# and print_roofit_pyz_doctrings.py
-ls $DOXYGEN_PYZDOC_PATH/*.pyzdoc | sed -e "s/$/ \\\\/"  \
->> Doxyfile_INPUT
-