Skip to content

Commit 7dda67c

Browse files
Krishna-13-cybervgvassilev
Krishna-13-cyber
authored and
vgvassilev
committed
Add initial setup for doxygen documentation
Signed-off-by: <[email protected]> Krishna Narayanan
1 parent a7f1ed9 commit 7dda67c

18 files changed

+2960
-0
lines changed

‎.readthedocs.yaml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: 2
2+
3+
sphinx:
4+
configuration: docs/conf.py
5+
builder: html
6+
7+
build:
8+
image: latest
9+
apt_packages:
10+
- clang-14
11+
- cmake
12+
- libclang-14-dev
13+
- llvm-14-dev
14+
- llvm-14-tools

‎CMakeLists.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,5 +345,14 @@ if (TARGET clang-headers)
345345
list(APPEND LLVM_COMMON_DEPENDS clang-headers)
346346
endif()
347347

348+
# Generate docs for CppInterOp
349+
option(INTEROP_INCLUDE_DOCS "Generate build targets for the CppInterOp docs.")
350+
option(INTEROP_ENABLE_DOXYGEN "Use doxygen to generate CppInterOp interal API documentation.")
351+
option(INTEROP_ENABLE_SPHINX "Use sphinx to generage CppInterOp user documentation")
352+
353+
if (INTEROP_INCLUDE_DOCS)
354+
add_subdirectory(docs)
355+
endif()
356+
348357
add_subdirectory(lib)
349358
add_subdirectory(unittests)

‎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()

‎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(interop_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-interop
14+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
15+
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
16+
COMMENT "Generate CppInterOp 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-cppinterop
31+
)

‎docs/DevelopersDocumentation.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
Developers Documentation
2+
-------------------------
3+
4+
Building from source
5+
---------------------
6+
7+
Clang-Repl
8+
===========
9+
10+
.. code-block:: bash
11+
12+
export INTEROP_DIR=$PWD/cppyy-backend/python/cppyy_backend
13+
14+
git clone https://github.com/compiler-research/CppInterOp.git
15+
16+
cd CppInterOp
17+
18+
mkdir build && cd build
19+
20+
INTEROP_BUILD_DIR=$(PWD)
21+
22+
cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR/build -DCMAKE_INSTALL_PREFIX=$INTEROP_DIR ..
23+
24+
cmake --build . --target install
25+
26+
27+
CppInterOp is a C++ Language Interoperability Layer
28+
29+
CppInterOp Internal Documentation
30+
=================================
31+
32+
CppInterOp maintains an internal Doxygen documentation of its components. Internal
33+
documentation aims to capture intrinsic details and overall usage of code
34+
components. The goal of internal documentation is to make the codebase easier
35+
to understand for the new developers.

‎docs/FAQ.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
FAQ
2+
*****

‎docs/InstallationAndUsage.rst

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
InstallationAndUsage
2+
---------------------
3+
4+
5+
Build cling with LLVM and clang:
6+
===================================
7+
8+
9+
.. code-block:: bash
10+
11+
git clone --depth=1 https://github.com/root-project/cling.git
12+
git clone --depth=1 -b cling-llvm13 https://github.com/root-project/llvm-project.git
13+
cd llvm-project
14+
mkdir build
15+
cd build
16+
cmake -DLLVM_ENABLE_PROJECTS=clang \
17+
-DLLVM_EXTERNAL_PROJECTS=cling \
18+
-DLLVM_EXTERNAL_CLING_SOURCE_DIR=../../cling \
19+
-DLLVM_TARGETS_TO_BUILD="host;NVPTX" \
20+
-DCMAKE_BUILD_TYPE=Release \
21+
-DLLVM_ENABLE_ASSERTIONS=ON \
22+
-DLLVM_USE_LINKER=lld \
23+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF \
24+
-DCLANG_ENABLE_ARCMT=OFF \
25+
-DCLANG_ENABLE_FORMAT=OFF \
26+
-DCLANG_ENABLE_BOOTSTRAP=OFF \
27+
../llvm
28+
cmake --build . --target clang --parallel $(nproc --all)
29+
cmake --build . --target cling --parallel $(nproc --all)
30+
cmake --build . --target gtest_main --parallel $(nproc --all)
31+
32+
Note down the llvm-project directory location as we will need it later:
33+
34+
cd ../
35+
export LLVM_DIR=$PWD
36+
cd ../
37+
38+
Clone the InterOp repo. Build it using cling and install. Note down the path to InterOp install directory. This will be referred to as INTEROP_DIR:
39+
40+
export INTEROP_DIR=$PWD/cppyy-backend/python/cppyy_backend
41+
git clone https://github.com/compiler-research/InterOp.git
42+
cd InterOp
43+
mkdir build && cd build
44+
INTEROP_BUILD_DIR=$(PWD)
45+
cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR/build -DCMAKE_INSTALL_PREFIX=$INTEROP_DIR ..
46+
cmake --build . --target install
47+
48+
Build Clang-Repl:
49+
=================
50+
51+
.. code-block:: text
52+
53+
54+
Get the llvm/release/16.x version:
55+
git clone https://github.com/llvm/llvm-project.git
56+
git checkout release/16.x
57+
58+
Patches for development
59+
compgen -G "../patches/llvm/clang16-*.patch" > /dev/null && find ../patches/llvm/clang16-*.patch -printf "%f\n"
60+
&& git apply ../patches/llvm/clang16-*.patch
61+
62+
63+
mkdir build
64+
cd build
65+
66+
Build Clang-16 :
67+
68+
cmake -DLLVM_ENABLE_PROJECTS=clang \
69+
-DLLVM_TARGETS_TO_BUILD="host;NVPTX" \
70+
-DCMAKE_BUILD_TYPE=Release \
71+
-DLLVM_ENABLE_ASSERTIONS=ON \
72+
-DLLVM_USE_LINKER=lld \
73+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF \
74+
-DCLANG_ENABLE_ARCMT=OFF \
75+
-DCLANG_ENABLE_FORMAT=OFF \
76+
-DCLANG_ENABLE_BOOTSTRAP=OFF \
77+
../llvm
78+
79+
80+
cmake --build . --target clang clang-repl --parallel $(nproc --all)
81+
82+
Note down the llvm-project directory location as we will need it later:
83+
cd ../
84+
export LLVM_DIR=$PWD
85+
cd ../
86+
87+
Export Commands:
88+
export CB_PYTHON_DIR="$PWD/cppyy-backend/python"
89+
export INTEROP_DIR="$CB_PYTHON_DIR/cppyy_backend"
90+
91+
92+
cmake -DCMAKE_BUILD_TYPE=Release \
93+
-DUSE_CLING=OFF \
94+
-DUSE_REPL=ON \
95+
-DLLVM_DIR=$LLVM_BUILD_DIR \
96+
-DLLVM_USE_LINKER=lld \
97+
-DBUILD_SHARED_LIBS=ON \
98+
-DCMAKE_INSTALL_PREFIX=$INTEROP_DIR \
99+
../
100+
101+
cmake --build . --target install --parallel $(nproc --all)
102+

‎docs/UsingCppInterOp.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Using CppInterop
2+
----------------
3+
4+
This section briefly describes all the key functionalities offered by CppInterop.
5+
If you are just getting started with CppInterop, then this is the best place to start.
6+
You may want to skim some sections on the first read.
7+
8+
In case you haven't installed CppInterop already, then please do before proceeding
9+
with this guide.
10+
11+
Let's get started.
12+
13+
C++ Language Interoperability Layer
14+
===================================
15+
16+

‎docs/conf.py

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'CppInterOp'
10+
copyright = '2023, Vassil Vassilev'
11+
author = 'Vassil Vassilev'
12+
release = 'Dev'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = []
18+
19+
templates_path = ['_templates']
20+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
21+
22+
23+
24+
# -- Options for HTML output -------------------------------------------------
25+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
26+
27+
html_theme = 'alabaster'
28+
html_static_path = ['_static']
29+
30+
INTEROP_ROOT = '..'
31+
32+
# html_extra_path = [INTEROP_ROOT + '/build/docs/doxygen/html']
33+
34+
import subprocess
35+
command = 'mkdir {0}/build; cd {0}/build; cmake ../ -DClang_DIR=/usr/lib/llvm-14/lib/cmake/clang\
36+
-DLLVM_DIR=/usr/lib/llvm-14 -DINTEROP_ENABLE_DOXYGEN=ON\
37+
-DINTEROP_INCLUDE_DOCS=ON'.format(INTEROP_ROOT)
38+
subprocess.call(command, shell=True)
39+
subprocess.call('doxygen {0}/build/docs/doxygen.cfg'.format(INTEROP_ROOT), shell=True)

‎docs/doxygen-mainpage.dox

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/// @mainpage CppInterOp
2+
///
3+
/// @section main_intro Introduction
4+
/// A Clang-based C++ Interoperability library, which allow C++ code to be accessed and used from other programming languages.
5+
/// This involves creating a bridge or wrapper that exposes C++ functionality through a language-specific API.
6+
/// The document explains the detailings of the API of the language interoperability layer. This library allows different languages
7+
/// to interoperate with C++ code, instantiate a template and execute it.
8+
///
9+
/// This documentation describes the @b internal software that makes
10+
/// up CppInterOp, not the @b external use of CppInterOp. There are no complete instructions
11+
/// here on how to use InterOp, only the APIs that make up the software. For
12+
/// usage instructions, please see the programmer's guide or reference
13+
/// manual.
14+
///
15+
/// @section main_caveat Caveat
16+
/// This documentation is generated directly from the source code with doxygen.
17+
/// Since CppInterOp is constantly under active development, what you're about to
18+
/// read is out of date!

0 commit comments

Comments
 (0)