Add documentation setup for xeus-clang-repl

.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "mambaforge-4.10"
+  apt_packages:
+    - clang-14
+    - libclang-14-dev
+    - llvm-14-dev
+    - llvm-14-tools
+
+conda:
+  environment: docs/environment.yml

CMakeLists.txt

@@ -50,9 +50,10 @@ if (LLVM_REQUIRED_VERSION)
 endif() 
 
 find_package(xeus ${xeus_REQUIRED_VERSION} REQUIRED)
-find_package(cppzmq ${cppzmq_REQUIRED_VERSION} REQUIRED)
+find_package(cppzmq REQUIRED CONFIG)
 find_package(pugixml REQUIRED)
 
+
 #find_package(LLVM REQUIRED CONFIG PATHS "${LLVM_CONFIG_EXTRA_PATH_HINTS}" NO_DEFAULT_PATH)
 #find_package(Clang REQUIRED CONFIG PATHS "${LLVM_CONFIG_EXTRA_PATH_HINTS}/lib/cmake/clang/" NO_DEFAULT_PATH)
 find_package(LLVM ${llvm_REQUIRED_VERSION} REQUIRED CONFIG PATHS "${LLVM_CONFIG_EXTRA_PATH_HINTS}")
@@ -274,3 +275,8 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/${PROJECT_NAME}Config.cmake
 install(EXPORT ${PROJECT_NAME}-targets
         FILE ${PROJECT_NAME}Targets.cmake
         DESTINATION ${XEUS_CLANG_REPL_CMAKECONFIG_INSTALL_DIR})
+
+# Documentation
+if(XEUS_CLANG_REPL_INCLUDE_DOCS)
+  add_subdirectory(docs)
+endif()

cmake/CreateSphinxTarget.cmake

@@ -0,0 +1,25 @@
+# Implementation of 'create_sphinx_target' in this file is copied from 
+# llvm implementation of 'AddSphinxTarget'.
+# https://github.com/llvm/llvm-project/blob/main/llvm/cmake/modules/AddSphinxTarget.cmake
+
+find_package(Sphinx REQUIRED)
+
+function(create_sphinx_target)
+  cmake_parse_arguments(SPHINX
+                        "" # options
+                        "SOURCE_DIR;TARGET_NAME"
+                        "" # multi-value keywords
+                        ${ARGN}
+                      )
+  set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/build)
+  set(SPHINX_DOC_TREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/_doctrees)
+
+  add_custom_target(${SPHINX_TARGET_NAME}
+                    COMMAND
+                    ${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} -q ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
+                    COMMENT
+                    "Generating sphinx user documentation into \"${SPHINX_BUILD_DIR}\""
+                    VERBATIM
+                  )
+  message(STATUS "Added ${SPHINX_TARGET_NAME} target")
+endfunction()

cmake/FindSphinx.cmake

@@ -0,0 +1,27 @@
+# CMake find_package() Module for Sphinx documentation generator
+# http://sphinx-doc.org/
+#
+# Example usage:
+#
+# find_package(Sphinx)
+#
+# If successful the following variables will be defined
+# SPHINX_FOUND
+# SPHINX_EXECUTABLE
+
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build sphinx-build2
+             DOC "Path to sphinx-build executable")
+
+# Handle REQUIRED and QUIET arguments
+# this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Sphinx
+                                  "Failed to locate sphinx-build executable"
+                                  SPHINX_EXECUTABLE)
+
+# Provide options for controlling different types of output
+option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
+option(SPHINX_OUTPUT_MAN "Output man pages" ON)
+
+option(SPHINX_WARNINGS_AS_ERRORS "When building documentation treat warnings as errors" ON)

cmake/modules/GoogleTest.cmake

@@ -0,0 +1,84 @@
+set(_gtest_byproduct_binary_dir
+  ${CMAKE_BINARY_DIR}/downloads/googletest-prefix/src/googletest-build)
+set(_gtest_byproducts
+  ${_gtest_byproduct_binary_dir}/lib/libgtest.a
+  ${_gtest_byproduct_binary_dir}/lib/libgtest_main.a
+  ${_gtest_byproduct_binary_dir}/lib/libgmock.a
+  ${_gtest_byproduct_binary_dir}/lib/libgmock_main.a
+  )
+
+if(MSVC)
+  set(EXTRA_GTEST_OPTS
+    -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=${_gtest_byproduct_binary_dir}/lib/
+    -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_MINSIZEREL:PATH=${_gtest_byproduct_binary_dir}/lib/
+    -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=${_gtest_byproduct_binary_dir}/lib/
+    -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELWITHDEBINFO:PATH=${_gtest_byproduct_binary_dir}/lib/
+    -Dgtest_force_shared_crt=ON
+    BUILD_COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config Release)
+elseif(APPLE)
+  set(EXTRA_GTEST_OPTS -DCMAKE_OSX_SYSROOT=${CMAKE_OSX_SYSROOT})
+endif()
+
+include(ExternalProject)
+ExternalProject_Add(
+  googletest
+  GIT_REPOSITORY https://github.com/google/googletest.git
+  GIT_SHALLOW 1
+  GIT_TAG release-1.12.1
+  UPDATE_COMMAND ""
+  # # Force separate output paths for debug and release builds to allow easy
+  # # identification of correct lib in subsequent TARGET_LINK_LIBRARIES commands
+  # CMAKE_ARGS -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=DebugLibs
+  #            -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=ReleaseLibs
+  #            -Dgtest_force_shared_crt=ON
+  CMAKE_ARGS -G ${CMAKE_GENERATOR}
+                -DCMAKE_BUILD_TYPE=Release
+                -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
+                -DCMAKE_C_FLAGS=${CMAKE_C_FLAGS}
+                -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
+                -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS}
+                -DCMAKE_AR=${CMAKE_AR}
+                -DCMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}
+                ${EXTRA_GTEST_OPTS}
+  # Disable install step
+  INSTALL_COMMAND ""
+  BUILD_BYPRODUCTS ${_gtest_byproducts}
+  # Wrap download, configure and build steps in a script to log output
+  LOG_DOWNLOAD ON
+  LOG_CONFIGURE ON
+  LOG_BUILD ON
+  TIMEOUT 600
+  )
+
+# Specify include dirs for gtest and gmock
+ExternalProject_Get_Property(googletest source_dir)
+set(GTEST_INCLUDE_DIR ${source_dir}/googletest/include)
+set(GMOCK_INCLUDE_DIR ${source_dir}/googlemock/include)
+# Create the directories. Prevents bug https://gitlab.kitware.com/cmake/cmake/issues/15052
+file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR} ${GMOCK_INCLUDE_DIR})
+
+# Libraries
+ExternalProject_Get_Property(googletest binary_dir)
+set(_G_LIBRARY_PATH ${binary_dir}/lib/)
+
+# Use gmock_main instead of gtest_main because it initializes gtest as well.
+# Note: The libraries are listed in reverse order of their dependancies.
+foreach(lib gtest gtest_main gmock gmock_main)
+  add_library(${lib} IMPORTED STATIC GLOBAL)
+  set_target_properties(${lib} PROPERTIES
+    IMPORTED_LOCATION "${_G_LIBRARY_PATH}${CMAKE_STATIC_LIBRARY_PREFIX}${lib}${CMAKE_STATIC_LIBRARY_SUFFIX}"
+    INTERFACE_INCLUDE_DIRECTORIES "${GTEST_INCLUDE_DIRS}"
+    )
+  add_dependencies(${lib} googletest)
+  if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" AND
+      ${CMAKE_CXX_COMPILER_VERSION} VERSION_GREATER_EQUAL 9)
+    target_compile_options(${lib} INTERFACE -Wno-deprecated-copy)
+  endif()
+endforeach()
+target_include_directories(gtest INTERFACE ${GTEST_INCLUDE_DIR})
+target_include_directories(gmock INTERFACE ${GMOCK_INCLUDE_DIR})
+
+set_property(TARGET gtest PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest${CMAKE_STATIC_LIBRARY_SUFFIX})
+set_property(TARGET gtest_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest_main${CMAKE_STATIC_LIBRARY_SUFFIX})
+set_property(TARGET gmock PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock${CMAKE_STATIC_LIBRARY_SUFFIX})
+set_property(TARGET gmock_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock_main${CMAKE_STATIC_LIBRARY_SUFFIX})

docs/CMakeLists.txt

@@ -0,0 +1,31 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in)
+set(DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg)
+
+set(docs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
+set(docs_builddir ${CMAKE_CURRENT_BINARY_DIR})
+set(xeus_clang_repl_srcdir ${CMAKE_SOURCE_DIR})
+# file(READ ${CMAKE_SOURCE_DIR}/VERSION PACKAGE_VERSION)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE} @ONLY)
+
+add_custom_target(doxygen-xeus_clang_repl
+                  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
+                  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+                  COMMENT "Generate xeus-clang-repl documentation with Doxygen"
+                  VERBATIM)
+
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
+include(CreateSphinxTarget)
+
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py 
+               ${CMAKE_CURRENT_BINARY_DIR}/conf.py
+               @ONLY
+              )
+
+create_sphinx_target(
+  SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
+  TARGET_NAME sphinx-xeus-clang-repl
+)

docs/DevelopersDocumentation.rst

@@ -0,0 +1,8 @@
+Developers Documentation
+------------------------
+Xeus-Clang-REPL maintains an internal Doxygen documentation of its components. Internal
+documentation aims to capture intrinsic details and overall usage of code
+components. The goal of internal documentation is to make the codebase easier
+to understand for the new developers.
+
+Internal documentation can be visited : `here </en/latest/build/html/index.html>`_

docs/FAQ.rst

@@ -0,0 +1,26 @@
+FAQ 
+---
+
+-   **What is Xeus-Clang-REPL?**
+    Xeus-Clang-REPL is an interactive programming environment that allows you to 
+    execute C++ code in a Jupyter Notebook using the Clang-REPL interpreter.
+
+-   **How do I install and build from source the Xeus-Clang-REPL?**
+    Installation instructions can typically be found in the project's documentation.
+    You can follow the guide here: :doc:`Installation and usage <InstallationAndUsage>`
+
+-   **What are the benefits of using Xeus-Clang-REPL?**
+    You can interactively run and debug C++ code in a Jupyter notebook.
+    You can use xeus-clang-repl to prototype C++ code quickly and easily.
+
+-   **How do I create a new session?**
+    To create a new Xeus-Clang-REPL session, you would open Jupyter Notebook,
+    select the appropriate kernel, and create a new notebook file.
+
+-   **Where can I find documentation and examples for Xeus-Clang-REPL?**
+    Documentation, tutorials, and references can be found on this Documentation 
+    itself, :doc:`Documentation <DevelopersDocumentation>`.
+
+-   **How do I contribute to the project?**
+    Instructions for reporting issues and contributing to the project are
+    provided in the repository's README or contributing guidelines.

docs/InstallationAndUsage.rst

@@ -0,0 +1,57 @@
+InstallationAndUsage
+--------------------
+
+You will first need to install dependencies.
+
+.. code-block:: bash
+
+    mamba install cmake cxx-compiler nlohmann_json cppzmq xtl jupyterlab 
+    clangdev=14 cxxopts pugixml -c conda-forge
+
+
+**Note:** Use a mamba environment with python version >= 3.11 for fetching clang-versions.
+
+The safest usage is to create an environment named `xeus-clang-repl`.
+
+.. code-block:: bash
+
+    mamba create -n  xeus-clang-repl
+    source activate  xeus-clang-repl
+
+
+Installing from conda-forge:
+Then you can install in this environment `xeus-clang-repl` and its dependencies.
+
+.. code-block:: bash
+
+    mamba install xeus-clang-repl notebook -c conda-forge
+
+.. code-block:: bash
+
+    git clone https://github.com/llvm/llvm-project
+
+    git checkout -b release/15.0x
+
+    git apply patches/llvm/clang15-D127284.patch
+
+    mkdir build
+
+    cd build
+
+    cmake -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" ../llvm
+
+    make -j n
+
+    cd ..
+
+    git clone https://github.com/compiler-research/xeus-clang-repl.git
+
+    mkdir build
+
+    cd build
+
+    # The clang project which we have built above has to be given in the LLVM path
+    cmake ../ -DClang_DIR=/usr/lib/llvm-15/build/lib/cmake/clang\
+            -DLLVM_DIR=/usr/lib/llvm-15/build/lib/cmake/llvm
+
+    make -j n

docs/UsingXeus-Clang-REPL.rst

@@ -0,0 +1,16 @@
+Using xeus-clang-repl
+---------------------
+
+- With xeus-clang-repl, you can write and execute C++ code interactively, seeing
+  the results immediately. This REPL nature allows you to iterate quickly
+  without the overhead of compiling and running separate C++ programs.
+
+- To achieve C++ and Python integration within a Jupyter environment we can use
+  xeus-clang-repl. Thereby you can write and execute C++ code interactively in
+  this environment.
+
+- Jupyter notebooks support magic commands (**%%python**) and inline code
+  execution for different languages. We use these features to run Python and C++
+  code in separate cells to achieve interactive communication between them.
+
+

docs/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Xeus-Clang-REPL'
+copyright = '2023,Compiler Research'
+author = 'Xeus-Clang-REPL Contributors'
+release = 'Dev'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+
+html_theme_options = {
+    "github_user": "Xeus-Clang-REPL Contributors",
+    "github_repo": "Xeus-Clang-REPL",
+    "github_banner": True,
+    "fixed_sidebar": True,
+}
+
+highlight_language = "C++"
+
+todo_include_todos = True
+
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+
+# Add latex physics package
+mathjax3_config = {
+    "loader": {"load": ["[tex]/physics"]},
+    "tex": {"packages": {"[+]": ["physics"]}},
+}
+
+import os
+XEUS_CLANG_REPL_ROOT = os.path.abspath('..')
+html_extra_path = [XEUS_CLANG_REPL_ROOT + '/build/docs/']
+
+import subprocess
+command = 'mkdir {0}/build; cd {0}/build; cmake ../ -DClang_DIR=/usr/lib/llvm-14/build/lib/cmake/clang\
+-DLLVM_DIR=/usr/lib/llvm-14/build/lib/cmake/llvm -DXEUS_CLANG_REPL_INCLUDE_DOCS=ON'.format(XEUS_CLANG_REPL_ROOT)
+subprocess.call(command, shell=True)
+subprocess.call('doxygen {0}/build/docs/doxygen.cfg'.format(XEUS_CLANG_REPL_ROOT), shell=True)