Update xeus-cpp documentation setup

.readthedocs.yaml

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

CMakeLists.txt

@@ -375,3 +375,6 @@ if(XEUS_CPP_EMSCRIPTEN_WASM_BUILD)
             DESTINATION ${CMAKE_INSTALL_BINDIR})
 endif ()
 
+if(XEUS_CPP_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_cpp_srcdir ${CMAKE_SOURCE_DIR})
+# file(READ ${CMAKE_SOURCE_DIR}/VERSION PACKAGE_VERSION)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE} @ONLY)
+
+add_custom_target(doxygen-xeus_cpp
+                  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
+                  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+                  COMMENT "Generate xeus-cpp 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-cpp
+)

docs/DevelopersDocumentation.rst

@@ -0,0 +1,8 @@
+Developers Documentation
+------------------------
+Xeus-cpp 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,40 @@
+FAQ 
+---
+
+-   **What is Xeus-cpp?**
+
+    Xeus-cpp is an interactive programming environment that allows you to 
+    execute C++ code in a Jupyter Notebook.
+
+-   **How do I install and build from source the Xeus-cpp?**
+
+    Installation instructions can 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-cpp?**
+
+    You can interactively run and debug C++ code in a Jupyter notebook.
+
+    - Rapid Prototyping: Quickly prototype and experiment with C++ code without
+      the need to create a full project or compile an entire codebase. 
+    - Immediate Feedback: As a REPL, xeus-cpp provides instant feedback as you
+      write and execute code. This helps catch errors early.
+    - Interactive Learning: Xeus-cpp allows learners to interactively
+      explore C++ concepts and practice coding in a controlled environment.
+    - Debugging: By isolating and testing specific pieces of code, you can more
+      easily identify and fix issues in small code snippets.
+
+-   **How do I create a new session?**
+
+    To create a new Xeus-cpp session, simply open Jupyter Notebook,
+    select the appropriate kernel, and create a new notebook file.
+
+-   **Where can I find documentation and examples for Xeus-cpp?**
+
+    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,31 @@
+InstallationAndUsage
+--------------------
+
+You will first need to install dependencies.
+
+.. code-block:: bash
+
+    mamba install cmake cxx-compiler xeus-zmq nlohmann_json cppzmq xtl jupyterlab
+    clangdev=16 cpp-argparse 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-cpp`.
+
+.. code-block:: bash
+
+    mamba create -n  xeus-cpp
+    source activate  xeus-cpp
+
+Installing from conda-forge:
+Then you can install in this environment `xeus-cpp` and its dependencies.
+
+.. code-block:: bash
+
+    mamba install xeus-cpp notebook -c conda-forge
+
+    mkdir build && cd build
+    cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX 
+    -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib
+    make && make install