Fix doc

alexander-penev · Dec 5, 2023 · b20441d · b20441d
1 parent 64ba2a8
commit b20441d
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 107 deletions.
diff --git a/docs/userDocs/source/index.rst b/docs/userDocs/source/index.rst
@@ -70,7 +70,7 @@ Features
   automatic differentiation is not feasible.
 
 
-.. comment::
+.. comment
 
    .. todo::
 

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
diff --git a/docs/userDocs/source/user/UsingClad.rst b/docs/userDocs/source/user/UsingClad.rst
@@ -65,7 +65,7 @@ An example that demonstrates the usage of
    int main() {
      // differentiate 'fn' w.r.t 'x'.
      auto d_fn_1 = clad::differentiate(fn, "x");
-  
+
      // computes derivative of 'fn' w.r.t 'x' when (x, y) = (3, 4).
      std::cout<<d_fn_1.execute(3, 4)<<"\n"; // prints 6
    }
@@ -77,8 +77,8 @@ equivalent::
 
   clad::differentiate(fn, "x");
 
-and:: 
-  
+and::
+
   clad::differentiate(fn, 0);
 
 The derived function is executed by calling the ``.execute`` method on the associated ``clad::CladFunction`` object. 

diff --git a/docs/userDocs/source/user/UsingEnzymeWithinClad.rst b/docs/userDocs/source/user/UsingEnzymeWithinClad.rst
@@ -35,7 +35,7 @@ something like this
 
 .. code-block:: bash
 
-    cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11
+   cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11
     -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``"
     -DENABLE_ENZYME_BACKEND=On
 

diff --git a/docs/userDocs/source/user/UsingVectorMode.rst b/docs/userDocs/source/user/UsingVectorMode.rst
@@ -2,8 +2,8 @@ Using Vector Mode for Differentiation
 **************************************
 
 .. note::
-    This feature is still under development and may result in unexpected
-    behavior. Please report any issues you find.
+   This feature is still under development and may result in unexpected
+   behavior. Please report any issues you find.
 
 For forward mode AD, the restriction is that the function can be only be
 differentiated with respect to a single input variable. However, in many cases,