Add a test build of documentation in CI (#663)

vgvassilev · Dec 5, 2023 · 5c248da · 5c248da
1 parent cc034ea
commit 5c248da
Show file tree

Hide file tree

Showing 9 changed files with 142 additions and 113 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -388,14 +388,20 @@ jobs:
             clang-runtime: '16'
             debug_build: true
 
+          - name: ubuntu-clang15-runtime16-doc
+            os: ubuntu-latest
+            compiler: clang-15
+            clang-runtime: '16'
+            doc_build: true
+
     steps:
     - uses: actions/checkout@v3
       with:
         fetch-depth: 0
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: 3.7
+        python-version: 3.11
     - name: Save PR Info
       if: ${{ matrix.coverage == true }}
       run: |
@@ -779,6 +785,24 @@ jobs:
         done
 
         cd ..
+    - name: Test build sphinx & doxygen documentation
+      if: ${{ (matrix.doc_build == true) }}
+      run: |
+        sudo apt-get install -y doxygen graphviz
+        pip install --upgrade pip
+        pip install -r requirements.txt
+        mkdir -p obj && cd obj
+        cmake \
+          -DClang_DIR="$PATH_TO_LLVM_BUILD" \
+          -DLLVM_DIR="$PATH_TO_LLVM_BUILD"  \
+          -DCLAD_INCLUDE_DOCS=ON            \
+          -DCLAD_ENABLE_DOXYGEN=ON          \
+          -DCLAD_ENABLE_SPHINX=ON           \
+          -DCMAKE_INSTALL_PREFIX=../inst    \
+          -DCMAKE_BUILD_TYPE=Debug          \
+          -DLLVM_EXTERNAL_LIT="`which lit`" \
+          ..
+        cmake --build . --target sphinx-clad doxygen-clad -- -j4
     - name: Failed job config
       if: ${{ failure() && runner.os != 'windows' }}
       env:
@@ -804,7 +828,7 @@ jobs:
       if: ${{ failure() }}
       uses: mxschmitt/action-tmate@v3
       # When debugging increase to a suitable value!
-      timeout-minutes: ${{ github.event.pull_request && 1 || 20 }}
+      timeout-minutes: ${{ github.event.pull_request && 100 || 20 }}
     - name: Prepare code coverage report
       if: ${{ success() && (matrix.coverage == true) }}
       run: |

diff --git a/cmake/CreateSphinxTarget.cmake b/cmake/CreateSphinxTarget.cmake
@@ -16,7 +16,7 @@ function(create_sphinx_target)
 
   add_custom_target(${SPHINX_TARGET_NAME}
                     COMMAND
-                    ${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} -q ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
+                    ${SPHINX_EXECUTABLE} -W --keep-going -b html -d ${SPHINX_DOC_TREE_DIR} ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
                     COMMENT
                     "Generating sphinx user documentation into \"${SPHINX_BUILD_DIR}\""
                     VERBATIM

diff --git a/docs/userDocs/source/index.rst b/docs/userDocs/source/index.rst
@@ -70,7 +70,8 @@ Features
   automatic differentiation is not feasible.
 
 
-.. comment::
+.. comment
+
 
    .. todo::
 
@@ -88,6 +89,7 @@ The User Guide
    user/reference
    user/tutorials
    user/UsingEnzymeWithinClad
+   user/UsingVectorMode.rst
    user/FAQ
    user/DevelopersDocumentation
    user/FloatingPointErrorEstimation

diff --git a/docs/userDocs/source/user/DevelopersDocumentation.rst b/docs/userDocs/source/user/DevelopersDocumentation.rst
@@ -9,12 +9,12 @@ Linux (Ubuntu)
 
 .. code-block:: bash
 
-  sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev
-  sudo -H pip install lit
-  git clone https://github.com/vgvassilev/clad.git clad
-  mkdir build_dir inst; cd build_dir
-  cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``"
-  make && make install
+   sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev
+   sudo -H pip install lit
+   git clone https://github.com/vgvassilev/clad.git clad
+   mkdir build_dir inst; cd build_dir
+   cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``"
+   make && make install
 
 
 Instructions to build documentation
@@ -27,7 +27,7 @@ This will also install the correct version of `sphinx` :
 
 .. code-block:: bash
 
-  pip install -r requirements.txt
+   pip install -r requirements.txt
 
 Make sure `doxygen` is installed if you want to build the internal documentation : 
 
@@ -40,8 +40,8 @@ To build clad and its documentation, use the following CMake command:
 
 .. code-block:: bash
 
-  cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCLAD_INCLUDE_DOCS=ON -DCLAD_ENABLE_DOXYGEN=ON -DCLAD_ENABLE_SPHINX=ON -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``"
-  make sphinx-clad doxygen-clad
+   cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCLAD_INCLUDE_DOCS=ON -DCLAD_ENABLE_DOXYGEN=ON -DCLAD_ENABLE_SPHINX=ON -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``"
+   make sphinx-clad doxygen-clad
 
 The built user documentation can be found in `build/docs/userDocs/build`; 
 while the built internal documentation can be found in `build/docs/internalDocs/build`.
@@ -61,16 +61,16 @@ In brief, debug build of LLVM with Clang enabled can be built using the followin
 instructions:
 
 .. code-block:: bash
-  
-  sudo -H pip install lit
-  git clone https://github.com/llvm/llvm-project.git
-  cd llvm-project
-  git checkout release/12.x
-  cd ../
-  mkdir obj inst
-  cd obj
-  cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst
-  make install
+
+   sudo -H pip install lit
+   git clone https://github.com/llvm/llvm-project.git
+   cd llvm-project
+   git checkout release/12.x
+   cd ../
+   mkdir obj inst
+   cd obj
+   cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst
+   make install
 
 Please note that it is recommended to have at least 16 GB of total memory (RAM + swap) to build LLVM in debug mode.
 
@@ -98,7 +98,7 @@ After incorporating all of these tweaks, the CMake command should look like this
 
 .. code-block:: bash
 
-  cmake -G Ninja /path/to/llvm-project/llvm -DLLVM_USE_LINKER=gold -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DBUILD_SHARED_LIBS=On -DLLVM_USE_SPLIT_DWARF=On -DLLVM_OPTIMIZED_TABLEGEN=On -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst
+   cmake -G Ninja /path/to/llvm-project/llvm -DLLVM_USE_LINKER=gold -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DBUILD_SHARED_LIBS=On -DLLVM_USE_SPLIT_DWARF=On -DLLVM_OPTIMIZED_TABLEGEN=On -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst
 
 Clad Internal Documentation
 =================================
@@ -159,61 +159,61 @@ For example,
 
 .. code-block:: bash
 
-  clang++ -g hello-world.cpp -fsyntax-only -v
+   clang++ -g hello-world.cpp -fsyntax-only -v
 
 This command will give output similar to
 
 .. code-block:: bash
 
-  Ubuntu clang version 11.1.0-6
-  Target: x86_64-pc-linux-gnu
-  Thread model: posix
-  InstalledDir: /home/parth/Programs/bin
-  Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11
-  Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11
-  Candidate multilib: .;@m64
-  Selected multilib: .;@m64
-   (in-process)
-   "/usr/lib/llvm-11/bin/clang" -cc1 -triple x86_64-pc-linux-gnu 
-   -fsyntax-only -disable-free -disable-llvm-verifier -discard-value-names
-   -main-file-name hello-world.cpp -mrelocation-model static 
-   -mframe-pointer=all -fmath-errno -fno-rounding-math -mconstructor-aliases 
-   -munwind-tables -target-cpu x86-64 -fno-split-dwarf-inlining 
-   -debug-info-kind=limited -dwarf-version=4 -debugger-tuning=gdb 
-   -v -resource-dir /usr/lib/llvm-11/lib/clang/11.1.0 
-   -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 
-   -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 
-   -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 
-   -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward 
-   -internal-isystem /usr/local/include -internal-isystem /usr/lib/llvm-11/lib/clang/11.1.0/include 
-   -internal-externc-isystem /usr/include/x86_64-linux-gnu -internal-externc-isystem /include 
-   -internal-externc-isystem /usr/include -fdeprecated-macro -fdebug-compilation-dir /home/parth 
-   -ferror-limit 19 -fgnuc-version=4.2.1 -fcxx-exceptions -fexceptions -faddrsig -x c++ hello-world.cpp
-  
-  clang -cc1 version 11.1.0 based upon LLVM 11.1.0 default target x86_64-pc-linux-gnu
-  ignoring nonexistent directory "/include"
-  ignoring duplicate directory "/usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11"
-  #include "..." search starts here:
-  #include <...> search starts here:
-   /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11
-   /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11
-   /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward
-   /usr/local/include
-   /usr/lib/llvm-11/lib/clang/11.1.0/include
-   /usr/include/x86_64-linux-gnu
-   /usr/include
-  End of search list.
+   Ubuntu clang version 11.1.0-6
+   Target: x86_64-pc-linux-gnu
+   Thread model: posix
+   InstalledDir: /home/parth/Programs/bin
+   Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11
+   Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11
+   Candidate multilib: .;@m64
+   Selected multilib: .;@m64
+    (in-process)
+    "/usr/lib/llvm-11/bin/clang" -cc1 -triple x86_64-pc-linux-gnu 
+    -fsyntax-only -disable-free -disable-llvm-verifier -discard-value-names
+    -main-file-name hello-world.cpp -mrelocation-model static 
+    -mframe-pointer=all -fmath-errno -fno-rounding-math -mconstructor-aliases 
+    -munwind-tables -target-cpu x86-64 -fno-split-dwarf-inlining 
+    -debug-info-kind=limited -dwarf-version=4 -debugger-tuning=gdb 
+    -v -resource-dir /usr/lib/llvm-11/lib/clang/11.1.0 
+    -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 
+    -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 
+    -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 
+    -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward 
+    -internal-isystem /usr/local/include -internal-isystem /usr/lib/llvm-11/lib/clang/11.1.0/include 
+    -internal-externc-isystem /usr/include/x86_64-linux-gnu -internal-externc-isystem /include 
+    -internal-externc-isystem /usr/include -fdeprecated-macro -fdebug-compilation-dir /home/parth 
+    -ferror-limit 19 -fgnuc-version=4.2.1 -fcxx-exceptions -fexceptions -faddrsig -x c++ hello-world.cpp
+   
+   clang -cc1 version 11.1.0 based upon LLVM 11.1.0 default target x86_64-pc-linux-gnu
+   ignoring nonexistent directory "/include"
+   ignoring duplicate directory "/usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11"
+   #include "..." search starts here:
+   #include <...> search starts here:
+    /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11
+    /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11
+    /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward
+    /usr/local/include
+    /usr/lib/llvm-11/lib/clang/11.1.0/include
+    /usr/include/x86_64-linux-gnu
+    /usr/include
+   End of search list.
 
 With the compiler invocation command in hand, we are ready to debug the compiler. 
 
 A typical example that demonstrates debugging of a program using ``lldb``
 
 .. code-block:: bash
 
-  lldb clang
-  # set breakpoints
-  breakpoint set -n "clang::Sema::BuildDeclRefExpr"
-  process launch -- {compiler-invocation-arguments}
+   lldb clang
+   # set breakpoints
+   breakpoint set -n "clang::Sema::BuildDeclRefExpr"
+   process launch -- {compiler-invocation-arguments}
 
 Replace ``{compiler-invocation-arguments}`` with the compiler invocation arguments
 obtained by executing the Clang driver command with ``-v`` option.

diff --git a/docs/userDocs/source/user/InstallationAndUsage.rst b/docs/userDocs/source/user/InstallationAndUsage.rst
@@ -12,15 +12,15 @@ Clad is available using conda <https://anaconda.org/conda-forge/clad>:
 
 .. code-block:: bash
 
-  conda install -c conda-forge clad
+   conda install -c conda-forge clad
 
 
 If you have already added ``conda-forge`` as a channel, the ``-c conda-forge`` is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions:
 
 .. code-block:: bash
 
-  conda config --add channels conda-forge
-  conda update --all
+   conda config --add channels conda-forge
+   conda update --all
 
 
 Building from source
@@ -31,43 +31,43 @@ Building from source (example was tested on Ubuntu 20.04 LTS)
 
 .. code-block:: bash
 
-  #sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev
-  sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
-  sudo -H pip install lit
-  git clone https://github.com/vgvassilev/clad.git clad
-  mkdir build_dir inst; cd build_dir
-  cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``"
-  make && make install
-  
+   #sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev
+   sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
+   sudo -H pip install lit
+   git clone https://github.com/vgvassilev/clad.git clad
+   mkdir build_dir inst; cd build_dir
+   cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``"
+   make && make install
+   
 Building from source (example was tested on macOS Catalina 10.15.7)
 --------------------------------------------------------------------
 
 .. code-block:: bash
 
-  brew install llvm@12
-  brew install python
-  python -m pip install lit
-  git clone https://github.com/vgvassilev/clad.git clad
-  mkdir build_dir inst; cd build_dir
-  cmake ../clad -DLLVM_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/llvm -DClang_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``"
-  make && make install
-  make check-clad
-  
+   brew install llvm@12
+   brew install python
+   python -m pip install lit
+   git clone https://github.com/vgvassilev/clad.git clad
+   mkdir build_dir inst; cd build_dir
+   cmake ../clad -DLLVM_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/llvm -DClang_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``"
+   make && make install
+   make check-clad
+   
 Building from source LLVM, Clang and Clad (development environment)
 --------------------------------------------------------------------
 
 .. code-block:: bash
 
-  sudo -H pip install lit
-  git clone https://github.com/llvm/llvm-project.git src
-  cd src; git chekout llvmorg-13.0.0
-  cd /tools
-  git clone https://github.com/vgvassilev/clad.git clad
-  cd ../../../
-  mkdir obj inst
-  cd obj
-  cmake -S ../src/llvm -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="Debug" -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_INSTALL_PREFIX=../inst 
-  make && make install
+   sudo -H pip install lit
+   git clone https://github.com/llvm/llvm-project.git src
+   cd src; git chekout llvmorg-13.0.0
+   cd /tools
+   git clone https://github.com/vgvassilev/clad.git clad
+   cd ../../../
+   mkdir obj inst
+   cd obj
+   cmake -S ../src/llvm -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="Debug" -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_INSTALL_PREFIX=../inst 
+   make && make install
 
 How to use Clad
 =================
@@ -80,9 +80,10 @@ xeus-cling <https://github.com/jupyter-xeus/xeus-cling> provides a Jupyter kerne
 To set up your environment, use:
 
 .. code-block:: bash
-  mamba create -n xeus-clad -c conda-forge clad xeus-cling jupyterlab
-  conda activate xeus-clad
-  jupyter notebook
+
+   mamba create -n xeus-clad -c conda-forge clad xeus-cling jupyterlab
+   conda activate xeus-clad
+   jupyter notebook
 
 The above will launch Jupyter with 3 Clad attached kernels for C++ 11/14/17.
 
@@ -95,25 +96,25 @@ Since Clad is a Clang plugin, it must be properly attached when the Clang compil
 
 .. code-block:: bash
 
-  clang -cc1 -x c++ -std=c++11 -load /full/path/to/lib/clad.so -plugin clad SourceFile.cpp
+   clang -cc1 -x c++ -std=c++11 -load /full/path/to/lib/clad.so -plugin clad SourceFile.cpp
 
 To compile using Clang < 10 , for example with clang-9, use:
 
 .. code-block:: bash
 
-  clang-9 -I /full/path/to/include/  -x c++ -std=c++11 -fplugin=/full/path/to/lib/clad.so SourceFile.cpp -o sourcefile -lstdc++ -lm
+   clang-9 -I /full/path/to/include/  -x c++ -std=c++11 -fplugin=/full/path/to/lib/clad.so SourceFile.cpp -o sourcefile -lstdc++ -lm
 
 To save the Clad generated derivative code to `Derivatives.cpp` add:
 
 .. code-block:: bash
 
-  -Xclang -plugin-arg-clad -Xclang -fgenerate-source-file
+   -Xclang -plugin-arg-clad -Xclang -fgenerate-source-file
 
 To print the Clad generated derivative add:
 
 .. code-block:: bash
 
-  -Xclang -plugin-arg-clad -Xclang -fdump-derived-fn
+   -Xclang -plugin-arg-clad -Xclang -fdump-derived-fn
 
 
 Note: Clad does not work with the Apple releases of Clang