Commit 1e0a4206 authored by Steffen Vogel's avatar Steffen Vogel 🎅🏼
Browse files

documentation: added C++ documentation to Sphinx (via Doxygen + Breathe)

parent 7bae83fe
......@@ -36,4 +36,6 @@ RUN pip3 install \
pandas \
numpy \
matplotlib \
sphinx
sphinx \
m2r \
breathe
find_package(Sphinx)
if(SPHINX_EXECUTABLE)
# configured documentation tools and intermediate build results
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")
if(NOT DEFINED SPHINX_THEME)
set(SPHINX_THEME alabaster)
endif()
if(NOT DEFINED SPHINX_THEME_DIR)
set(SPHINX_THEME_DIR)
endif()
# configured documentation tools and intermediate build results
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
# HTML output directory
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(SPHINX_TITLE "${PROJECT_NAME} Documentation")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${BINARY_BUILD_DIR}/conf.py"
@ONLY
)
# We add the path of the freshly build dpsim.so module to Python path here
add_custom_target(docs
${CMAKE_COMMAND} -E env PYTHONPATH=$<TARGET_FILE_DIR:dpsim>:$ENV{PYTHONPATH}
${SPHINX_EXECUTABLE}
-q -b html
-c "${BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx"
DEPENDS link_dpsim)
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
# HTML output directory
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(SPHINX_TITLE "${PROJECT_NAME} Documentation")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${BINARY_BUILD_DIR}/conf.py"
@ONLY
)
# Copy figures into Sphinx working directory
add_custom_target(copy_imgs
COMMAND
${CMAKE_COMMAND} -E make_directory
"${CMAKE_CURRENT_BINARY_DIR}/html/Figures/"
COMMAND
${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/../Figures/dpsim.png"
"${CMAKE_CURRENT_SOURCE_DIR}/../Figures/eonerc_logo.png"
"${CMAKE_CURRENT_BINARY_DIR}/html/Figures/"
COMMENT "Copying figures to Sphinx output dir"
)
# We add the path of the freshly build dpsim.so module to Python path here
add_custom_target(docs
COMMAND
${CMAKE_COMMAND} -E env PYTHONPATH=$<TARGET_FILE_DIR:dpsim>:$ENV{PYTHONPATH}
${SPHINX_EXECUTABLE}
-q -b html
-c "${BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx"
DEPENDS
link_dpsim
copy_imgs
docs_cxx
)
endif()
# add a target to generate API documentation with Doxygen
......@@ -45,16 +54,19 @@ find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
# HTML output directory
set(DOXYGEN_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/Cxx")
file(MAKE_DIRECTORY ${DOXYGEN_HTML_DIR})
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY
)
add_custom_target(docs_cxx
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
# HTML output directory
set(DOXYGEN_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/Cxx")
file(MAKE_DIRECTORY ${DOXYGEN_HTML_DIR})
add_custom_target(docs_cxx
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
endif(DOXYGEN_FOUND)
......@@ -1946,7 +1946,7 @@ MAN_LINKS = NO
# captures the structure of the code including all documentation.
# The default value is: NO.
GENERATE_XML = NO
GENERATE_XML = YES
# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
......
../Figures/
\ No newline at end of file
Build DPsim
===========
Building
========
DPsim
^^^^^
Windows (Visual Studio)
-----------------------
......@@ -58,8 +61,8 @@ Linux (CMake)
.. _DPsim: https://git.rwth-aachen.de/acs/core/simulation/dpsim
.. _`DPsim Libraries`: https://git.rwth-aachen.de/acs/core/simulation/dpsim-libraries
Build Documentation
===================
Documentation
^^^^^^^^^^^^^
Python
------
......
......@@ -31,7 +31,7 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc']
extensions = ['sphinx.ext.autodoc', 'm2r', 'breathe' ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
......@@ -39,8 +39,8 @@ templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = ['.rst', '.md']
#source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
......@@ -57,7 +57,7 @@ author = '@PROJECT_AUTHOR@'
# The short X.Y version.
version = '@DPSIM_VERSION@'
# The full version, including alpha/beta/rc tags.
release = ''
release = '@DPSIM_VERSION@-@DPSIM_RELEASE@'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -83,18 +83,23 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = '@SPHINX_THEME@'
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
html_theme_options = {
'analytics_id' : 'UA-110889373-2',
'show_related' : True
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
html_static_path = [ ]
html_logo = '@CMAKE_SOURCE_DIR@/Figures/dpsim.png'
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
......@@ -111,6 +116,10 @@ html_sidebars = {
]
}
html_context = {
'source_url_prefix': "https://git.rwth-aachen.org/acs/core/simulation/DPsim/HEAD/Documentation/",
}
# -- Options for HTMLHelp output ------------------------------------------
......@@ -171,6 +180,7 @@ texinfo_documents = [
default_role = 'any'
# Add the CMake build directory to the path
import sys
sys.path.insert(0, '@CMAKE_BINARY_DIR@/Source')
# -- Options for Breathe -------------------------------------------
breathe_projects = { 'dpsim' : '@CMAKE_BINARY_DIR@/Documentation/Cxx/xml' }
breathe_default_project = 'dpsim'
C++ API
=======
.. doxygenindex::
......@@ -3,14 +3,15 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to dpsim's documentation!
=================================
.. mdinclude:: ../README.md
.. toctree::
:maxdepth: 2
:caption: Contents:
module
guide
reference
main-doc-cpp
build
todo
......
Python module documentation
===========================
Python Module
=============
.. automodule:: dpsim
:members:
Reference
=========
.. toctree::
:maxdepth: 2
:caption: Contents:
python
cxx
The core simulation kernel of DPsim is implemented in C++.
For usability, Python bindings to some of the C++ code are provided.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment