Skip to content

Commit ae30c4a

Browse files
Krishna-13-cybervgvassilev
Krishna-13-cyber
authored and
vgvassilev
committed
Update xeus-cpp documentation setup
1 parent d529bdb commit ae30c4a

33 files changed

+3117
-505
lines changed

‎.readthedocs.yaml

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
11
version: 2
22

33
sphinx:
4-
configuration: docs/source/conf.py
4+
configuration: docs/conf.py
55
builder: html
66

7+
build:
8+
os: "ubuntu-22.04"
9+
tools:
10+
python: "mambaforge-22.9"
11+
apt_packages:
12+
- clang-15
13+
- libclang-15-dev
14+
- llvm-15-dev
15+
- llvm-15-tools
16+
717
conda:
818
environment: docs/environment.yml

‎CMakeLists.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -375,3 +375,6 @@ if(XEUS_CPP_EMSCRIPTEN_WASM_BUILD)
375375
DESTINATION ${CMAKE_INSTALL_BINDIR})
376376
endif ()
377377

378+
if(XEUS_CPP_INCLUDE_DOCS)
379+
add_subdirectory(docs)
380+
endif()

‎cmake/CreateSphinxTarget.cmake

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Implementation of 'create_sphinx_target' in this file is copied from
2+
# llvm implementation of 'AddSphinxTarget'.
3+
# https://github.com/llvm/llvm-project/blob/main/llvm/cmake/modules/AddSphinxTarget.cmake
4+
5+
find_package(Sphinx REQUIRED)
6+
7+
function(create_sphinx_target)
8+
cmake_parse_arguments(SPHINX
9+
"" # options
10+
"SOURCE_DIR;TARGET_NAME"
11+
"" # multi-value keywords
12+
${ARGN}
13+
)
14+
set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/build)
15+
set(SPHINX_DOC_TREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/_doctrees)
16+
17+
add_custom_target(${SPHINX_TARGET_NAME}
18+
COMMAND
19+
${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} -q ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
20+
COMMENT
21+
"Generating sphinx user documentation into \"${SPHINX_BUILD_DIR}\""
22+
VERBATIM
23+
)
24+
message(STATUS "Added ${SPHINX_TARGET_NAME} target")
25+
endfunction()

‎cmake/FindSphinx.cmake

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# CMake find_package() Module for Sphinx documentation generator
2+
# http://sphinx-doc.org/
3+
#
4+
# Example usage:
5+
#
6+
# find_package(Sphinx)
7+
#
8+
# If successful the following variables will be defined
9+
# SPHINX_FOUND
10+
# SPHINX_EXECUTABLE
11+
12+
find_program(SPHINX_EXECUTABLE
13+
NAMES sphinx-build sphinx-build2
14+
DOC "Path to sphinx-build executable")
15+
16+
# Handle REQUIRED and QUIET arguments
17+
# this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
18+
include(FindPackageHandleStandardArgs)
19+
find_package_handle_standard_args(Sphinx
20+
"Failed to locate sphinx-build executable"
21+
SPHINX_EXECUTABLE)
22+
23+
# Provide options for controlling different types of output
24+
option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
25+
option(SPHINX_OUTPUT_MAN "Output man pages" ON)
26+
27+
option(SPHINX_WARNINGS_AS_ERRORS "When building documentation treat warnings as errors" ON)

‎cmake/modules/GoogleTest.cmake

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
set(_gtest_byproduct_binary_dir
2+
${CMAKE_BINARY_DIR}/downloads/googletest-prefix/src/googletest-build)
3+
set(_gtest_byproducts
4+
${_gtest_byproduct_binary_dir}/lib/libgtest.a
5+
${_gtest_byproduct_binary_dir}/lib/libgtest_main.a
6+
${_gtest_byproduct_binary_dir}/lib/libgmock.a
7+
${_gtest_byproduct_binary_dir}/lib/libgmock_main.a
8+
)
9+
10+
if(MSVC)
11+
set(EXTRA_GTEST_OPTS
12+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=${_gtest_byproduct_binary_dir}/lib/
13+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_MINSIZEREL:PATH=${_gtest_byproduct_binary_dir}/lib/
14+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=${_gtest_byproduct_binary_dir}/lib/
15+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELWITHDEBINFO:PATH=${_gtest_byproduct_binary_dir}/lib/
16+
-Dgtest_force_shared_crt=ON
17+
BUILD_COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config Release)
18+
elseif(APPLE)
19+
set(EXTRA_GTEST_OPTS -DCMAKE_OSX_SYSROOT=${CMAKE_OSX_SYSROOT})
20+
endif()
21+
22+
include(ExternalProject)
23+
ExternalProject_Add(
24+
googletest
25+
GIT_REPOSITORY https://github.com/google/googletest.git
26+
GIT_SHALLOW 1
27+
GIT_TAG release-1.12.1
28+
UPDATE_COMMAND ""
29+
# # Force separate output paths for debug and release builds to allow easy
30+
# # identification of correct lib in subsequent TARGET_LINK_LIBRARIES commands
31+
# CMAKE_ARGS -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=DebugLibs
32+
# -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=ReleaseLibs
33+
# -Dgtest_force_shared_crt=ON
34+
CMAKE_ARGS -G ${CMAKE_GENERATOR}
35+
-DCMAKE_BUILD_TYPE=Release
36+
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
37+
-DCMAKE_C_FLAGS=${CMAKE_C_FLAGS}
38+
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
39+
-DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS}
40+
-DCMAKE_AR=${CMAKE_AR}
41+
-DCMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}
42+
${EXTRA_GTEST_OPTS}
43+
# Disable install step
44+
INSTALL_COMMAND ""
45+
BUILD_BYPRODUCTS ${_gtest_byproducts}
46+
# Wrap download, configure and build steps in a script to log output
47+
LOG_DOWNLOAD ON
48+
LOG_CONFIGURE ON
49+
LOG_BUILD ON
50+
TIMEOUT 600
51+
)
52+
53+
# Specify include dirs for gtest and gmock
54+
ExternalProject_Get_Property(googletest source_dir)
55+
set(GTEST_INCLUDE_DIR ${source_dir}/googletest/include)
56+
set(GMOCK_INCLUDE_DIR ${source_dir}/googlemock/include)
57+
# Create the directories. Prevents bug https://gitlab.kitware.com/cmake/cmake/issues/15052
58+
file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR} ${GMOCK_INCLUDE_DIR})
59+
60+
# Libraries
61+
ExternalProject_Get_Property(googletest binary_dir)
62+
set(_G_LIBRARY_PATH ${binary_dir}/lib/)
63+
64+
# Use gmock_main instead of gtest_main because it initializes gtest as well.
65+
# Note: The libraries are listed in reverse order of their dependancies.
66+
foreach(lib gtest gtest_main gmock gmock_main)
67+
add_library(${lib} IMPORTED STATIC GLOBAL)
68+
set_target_properties(${lib} PROPERTIES
69+
IMPORTED_LOCATION "${_G_LIBRARY_PATH}${CMAKE_STATIC_LIBRARY_PREFIX}${lib}${CMAKE_STATIC_LIBRARY_SUFFIX}"
70+
INTERFACE_INCLUDE_DIRECTORIES "${GTEST_INCLUDE_DIRS}"
71+
)
72+
add_dependencies(${lib} googletest)
73+
if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" AND
74+
${CMAKE_CXX_COMPILER_VERSION} VERSION_GREATER_EQUAL 9)
75+
target_compile_options(${lib} INTERFACE -Wno-deprecated-copy)
76+
endif()
77+
endforeach()
78+
target_include_directories(gtest INTERFACE ${GTEST_INCLUDE_DIR})
79+
target_include_directories(gmock INTERFACE ${GMOCK_INCLUDE_DIR})
80+
81+
set_property(TARGET gtest PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest${CMAKE_STATIC_LIBRARY_SUFFIX})
82+
set_property(TARGET gtest_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest_main${CMAKE_STATIC_LIBRARY_SUFFIX})
83+
set_property(TARGET gmock PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock${CMAKE_STATIC_LIBRARY_SUFFIX})
84+
set_property(TARGET gmock_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock_main${CMAKE_STATIC_LIBRARY_SUFFIX})

‎docs/CMakeLists.txt

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
find_package(Doxygen REQUIRED)
2+
3+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in)
4+
set(DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg)
5+
6+
set(docs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
7+
set(docs_builddir ${CMAKE_CURRENT_BINARY_DIR})
8+
set(xeus_cpp_srcdir ${CMAKE_SOURCE_DIR})
9+
# file(READ ${CMAKE_SOURCE_DIR}/VERSION PACKAGE_VERSION)
10+
11+
configure_file(${DOXYFILE_IN} ${DOXYFILE} @ONLY)
12+
13+
add_custom_target(doxygen-xeus_cpp
14+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
15+
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
16+
COMMENT "Generate xeus-cpp documentation with Doxygen"
17+
VERBATIM)
18+
19+
20+
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
21+
include(CreateSphinxTarget)
22+
23+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py
24+
${CMAKE_CURRENT_BINARY_DIR}/conf.py
25+
@ONLY
26+
)
27+
28+
create_sphinx_target(
29+
SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
30+
TARGET_NAME sphinx-xeus-cpp
31+
)

‎docs/DevelopersDocumentation.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Developers Documentation
2+
------------------------
3+
Xeus-cpp maintains an internal Doxygen documentation of its components. Internal
4+
documentation aims to capture intrinsic details and overall usage of code
5+
components. The goal of internal documentation is to make the codebase easier
6+
to understand for the new developers.
7+
8+
Internal documentation can be visited : `here </en/latest/build/html/index.html>`_

‎docs/Doxyfile

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎docs/FAQ.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
FAQ
2+
---
3+
4+
- **What is Xeus-cpp?**
5+
6+
Xeus-cpp is an interactive programming environment that allows you to
7+
execute C++ code in a Jupyter Notebook.
8+
9+
- **How do I install and build from source the Xeus-cpp?**
10+
11+
Installation instructions can be found in the project's documentation.
12+
You can follow the guide here: :doc:`Installation and usage <InstallationAndUsage>`
13+
14+
- **What are the benefits of using Xeus-cpp?**
15+
16+
You can interactively run and debug C++ code in a Jupyter notebook.
17+
18+
- Rapid Prototyping: Quickly prototype and experiment with C++ code without
19+
the need to create a full project or compile an entire codebase.
20+
- Immediate Feedback: As a REPL, xeus-cpp provides instant feedback as you
21+
write and execute code. This helps catch errors early.
22+
- Interactive Learning: Xeus-cpp allows learners to interactively
23+
explore C++ concepts and practice coding in a controlled environment.
24+
- Debugging: By isolating and testing specific pieces of code, you can more
25+
easily identify and fix issues in small code snippets.
26+
27+
- **How do I create a new session?**
28+
29+
To create a new Xeus-cpp session, simply open Jupyter Notebook,
30+
select the appropriate kernel, and create a new notebook file.
31+
32+
- **Where can I find documentation and examples for Xeus-cpp?**
33+
34+
Documentation, tutorials, and references can be found on this Documentation
35+
itself, :doc:`Documentation <DevelopersDocumentation>`.
36+
37+
- **How do I contribute to the project?**
38+
39+
Instructions for reporting issues and contributing to the project are
40+
provided in the repository's README or contributing guidelines.

‎docs/InstallationAndUsage.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
InstallationAndUsage
2+
--------------------
3+
4+
You will first need to install dependencies.
5+
6+
.. code-block:: bash
7+
8+
mamba install cmake cxx-compiler xeus-zmq nlohmann_json cppzmq xtl jupyterlab
9+
clangdev=16 cpp-argparse pugixml -c conda-forge
10+
11+
12+
**Note:** Use a mamba environment with python version >= 3.11 for fetching clang-versions.
13+
14+
The safest usage is to create an environment named `xeus-cpp`.
15+
16+
.. code-block:: bash
17+
18+
mamba create -n xeus-cpp
19+
source activate xeus-cpp
20+
21+
Installing from conda-forge:
22+
Then you can install in this environment `xeus-cpp` and its dependencies.
23+
24+
.. code-block:: bash
25+
26+
mamba install xeus-cpp notebook -c conda-forge
27+
28+
mkdir build && cd build
29+
cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX
30+
-D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib
31+
make && make install

0 commit comments

Comments
 (0)