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

Former-commit-id: 1e0a4206

Dockerfile

@@ -36,4 +36,6 @@ RUN pip3 install \
 	pandas \
 	numpy \
 	matplotlib \
-	sphinx
+	sphinx \
+	m2r \
+	breathe

Documentation/CMakeLists.txt

 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)

Documentation/Doxyfile.in.REMOVED.git-id

-7323db036ec471a6047dcc771ef92888b8331989
\ No newline at end of file
+47c0502c7e7220919a306d1f217ad26004eab742
\ No newline at end of file

Documentation/Figures

+../Figures/
\ No newline at end of file

Documentation/build.rst

-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
 ------

Documentation/conf.py.in

@@ -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'

Documentation/cxx.rst

+C++ API
+=======
+
+.. doxygenindex::

Documentation/index.rst

@@ -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
 

Documentation/module.rst → Documentation/python.rst

-Python module documentation
-===========================
+Python Module
+=============
 
 .. automodule:: dpsim
     :members:

Documentation/reference.rst

+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