-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add documentation setup for xeus-clang-repl
- Loading branch information
1 parent
9344d39
commit b860267
Showing
22 changed files
with
2,966 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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}) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>`_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
FAQ | ||
*** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
InstallationAndUsage | ||
-------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
Using xeus-clang-repl | ||
--------------------- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
/// @mainpage Xeus-Clang-Repl | ||
/// | ||
/// @section main_intro Introduction | ||
/// | ||
/// xeus-clang-repl is a Jupyter kernel for C++ based on the C++ interpreter clang-repl and | ||
/// the native implementation of the Jupyter protocol xeus. | ||
/// | ||
/// | ||
/// This documentation describes the @b internal software that makes | ||
/// up Xeus-Clang-Repl, not the @b external use of Xeus-Clang-Repl. There are no complete instructions | ||
/// here on how to use Xeus-Clang-Repl, only the APIs that make up the software. For | ||
/// usage instructions, please see the programmer's guide or reference | ||
/// manual. | ||
/// | ||
/// @section main_caveat Caveat | ||
/// This documentation is generated directly from the source code with doxygen. | ||
/// Since Xeus-Clang-Repl is constantly under active development, what you're about to | ||
/// read is out of date! |
Oops, something went wrong.