From 40c675f65f20f8cb92b51e4da1b0d4735930e37a Mon Sep 17 00:00:00 2001
From: Stephan Schulz <stephan.schulz-x2q@rub.de>
Date: Thu, 26 Nov 2020 12:54:58 +0100
Subject: [PATCH] fix sphinx and update doxygen (#29)
---
CMakeLists.txt | 5 ++-
docs/CMakeLists.txt | 26 ++++++++++++--
docs/Doxyfile.in | 63 ++++++++++++----------------------
docs/classes/ALL.rst | 4 +--
docs/classes/ALL_Functions.rst | 2 +-
docs/classes/ALL_Histogram.rst | 2 +-
docs/classes/ALL_LB.rst | 4 +--
docs/classes/ALL_Point.rst | 4 +--
docs/classes/ALL_Staggered.rst | 2 +-
docs/classes/ALL_Tensor.rst | 4 +--
docs/classes/ALL_Voronoi.rst | 9 +++++
11 files changed, 69 insertions(+), 56 deletions(-)
create mode 100644 docs/classes/ALL_Voronoi.rst
diff --git a/CMakeLists.txt b/CMakeLists.txt
index dacf1f7..c725b8d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -38,7 +38,10 @@ add_compile_options("$<$<AND:$<CONFIG:Debug>,$<COMPILE_LANGUAGE:Fortran>,$<Fortr
add_compile_options("$<$<AND:$<CONFIG:Debug>,$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:GNU>>:-Wall;-Wextra>")
add_compile_options("$<$<AND:$<CONFIG:Debug>,$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:GNU>>:-Wall;-Wextra>")
-project(ALL)
+project(ALL
+ VERSION "0.1.0"
+ DESCRIPTION "A Loadbalacing Library"
+ HOMEPAGE_URL "localhost")
# add custom find-scripts to module path
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 3f583b7..51bb235 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -1,17 +1,39 @@
message("Generating ALL Documentation:")
find_package(Doxygen REQUIRED)
+find_package(Python3 REQUIRED)
+message(DEBUG "Python3 version: ${PYTHON3_VERSION}")
find_package(Sphinx REQUIRED)
+#find breathe
+# todo(s.schulz): The following does not seem to work. It returns non zero even
+# though the package is installed and the correct Python interpreter is found.
+# The python interpreter is in a non standard path and included using
+# environment variables and the module was installed in the users directory
+# (pip3 install --user breathe).
+#execute_process(
+# COMMAND Python3::Interpreter -c "import breathe"
+# RESULT_VARIABLE BREATHE_NOT_FOUND
+# OUTPUT_QUIET
+# )
+#if(NOT ${BREATHE_NOT_FOUND} EQUAL 0)
+# message( FATAL_ERROR "Python \"breathe\" package not found")
+#endif()
+#do we need to make sure sphinx_rtd_theme is installed?
# Find all public headers
get_target_property(ALL_PUBLIC_HEADER_DIR ALL INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE ALL_PUBLIC_HEADERS ${ALL_PUBLIC_HEADER_DIR})
# setup configuring of doxygen
-set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include)
+# Caveat(s.schulz): Make sure there are not spaces within the paths.
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include ${PROJECT_SOURCE_DIR}/src ${PROJECT_SOURCE_DIR}/example)
+string(REPLACE ";" "\" \"" DOXYGEN_INPUT_DIR "${DOXYGEN_INPUT_DIR}")
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+set(DOXYGEN_INTERNAL_DOCS NO)
+set(DOXYGEN_EXAMPLE_PATH ${PROJECT_SOURCE_DIR}/example)
+set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md)
# configure doxygen config file
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
@@ -52,4 +74,4 @@ add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
include(GNUInstallDirs)
install(DIRECTORY ${SPHINX_BUILD}
-DESTINATION ${CMAKE_INSTALL_DOCDIR})
\ No newline at end of file
+DESTINATION ${CMAKE_INSTALL_DOCDIR})
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index cfdc315..c9237f6 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -32,19 +32,19 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.
-PROJECT_NAME = "MPCD"
+PROJECT_NAME = "@PROJECT_NAME@"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.
-PROJECT_NUMBER =
+PROJECT_NUMBER = "@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@"
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
-PROJECT_BRIEF =
+PROJECT_BRIEF = "@PROJECT_DESCRIPTION@"
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55
@@ -226,7 +226,7 @@ SEPARATE_MEMBER_PAGES = NO
# uses this value to replace tabs by spaces in code fragments.
# Minimum value: 1, maximum value: 16, default value: 4.
-TAB_SIZE = 4
+TAB_SIZE = 2
# This tag can be used to specify a number of aliases that act as commands in
# the documentation. An alias has the form:
@@ -328,7 +328,7 @@ AUTOLINK_SUPPORT = YES
# diagrams that involve STL classes more complete and accurate.
# The default value is: NO.
-BUILTIN_STL_SUPPORT = NO
+BUILTIN_STL_SUPPORT = YES
# If you use Microsoft's C++/CLI language, you should set this option to YES to
# enable parsing support.
@@ -397,7 +397,7 @@ INLINE_GROUPED_CLASSES = NO
# Man pages) or section (for LaTeX and RTF).
# The default value is: NO.
-INLINE_SIMPLE_STRUCTS = NO
+INLINE_SIMPLE_STRUCTS = YES
# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or
# enum is documented as struct, union, or enum with the name of the typedef. So
@@ -515,7 +515,7 @@ HIDE_IN_BODY_DOCS = NO
# will be excluded. Set it to YES to include the internal documentation.
# The default value is: NO.
-INTERNAL_DOCS = NO
+INTERNAL_DOCS = @DOXYGEN_INTERNAL_DOCS@
# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
# names in lower-case letters. If set to YES, upper-case letters are also
@@ -578,7 +578,7 @@ SORT_MEMBER_DOCS = YES
# this will also influence the order of the classes in the class list.
# The default value is: NO.
-SORT_BRIEF_DOCS = NO
+SORT_BRIEF_DOCS = YES
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
@@ -590,7 +590,7 @@ SORT_BRIEF_DOCS = NO
# detailed member documentation.
# The default value is: NO.
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
@@ -623,7 +623,7 @@ STRICT_PROTO_MATCHING = NO
# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
-GENERATE_TODOLIST = YES
+GENERATE_TODOLIST = NO
# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
# list. This list is created by putting \test commands in the documentation.
@@ -820,45 +820,24 @@ FILE_PATTERNS = *.c \
*.cxx \
*.cpp \
*.c++ \
- *.java \
- *.ii \
- *.ixx \
- *.ipp \
- *.i++ \
- *.inl \
- *.idl \
- *.ddl \
- *.odl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
- *.cs \
- *.d \
- *.php \
- *.php4 \
- *.php5 \
- *.phtml \
*.inc \
- *.m \
*.markdown \
*.md \
- *.mm \
*.dox \
*.py \
*.pyw \
*.f90 \
+ *.F90 \
*.f95 \
*.f03 \
*.f08 \
*.f \
- *.for \
- *.tcl \
- *.vhd \
- *.vhdl \
- *.ucf \
- *.qsf
+ *.for
# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
@@ -906,7 +885,7 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = "@DOXYGEN_EXAMPLE_PATH@"
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -982,7 +961,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = "@DOXYGEN_USE_MDFILE_AS_MAINPAGE@"
#---------------------------------------------------------------------------
# Configuration options related to source browsing
@@ -995,7 +974,7 @@ USE_MDFILE_AS_MAINPAGE =
# also VERBATIM_HEADERS is set to NO.
# The default value is: NO.
-SOURCE_BROWSER = NO
+SOURCE_BROWSER = YES
# Setting the INLINE_SOURCES tag to YES will include the body of functions,
# classes and enums directly into the documentation.
@@ -1249,7 +1228,7 @@ HTML_TIMESTAMP = NO
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_DYNAMIC_SECTIONS = NO
+HTML_DYNAMIC_SECTIONS = YES
# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
# shown in the various tree structured indices initially; the user can expand
@@ -1478,7 +1457,7 @@ DISABLE_INDEX = NO
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
-GENERATE_TREEVIEW = NO
+GENERATE_TREEVIEW = YES
# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
# doxygen will group on one line in the generated HTML documentation.
@@ -1666,7 +1645,7 @@ EXTRA_SEARCH_MAPPINGS =
# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.
-GENERATE_LATEX = YES
+GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2099,7 +2078,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED =
+PREDEFINED = ALL_VORONOI_ACTIVE ALL_VTK_OUTPUT
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
@@ -2331,7 +2310,7 @@ INCLUDED_BY_GRAPH = YES
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
-CALL_GRAPH = NO
+CALL_GRAPH = YES
# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
# dependency graph for every global function or class method.
@@ -2343,7 +2322,7 @@ CALL_GRAPH = NO
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
-CALLER_GRAPH = NO
+CALLER_GRAPH = YES
# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
# hierarchy of all classes instead of a textual one.
diff --git a/docs/classes/ALL.rst b/docs/classes/ALL.rst
index e28b5ef..468be03 100644
--- a/docs/classes/ALL.rst
+++ b/docs/classes/ALL.rst
@@ -2,8 +2,8 @@
ALL
===
-.. doxygenclass:: ALL
+.. doxygenclass:: ALL::ALL
:members:
:protected-members:
:private-members:
- :undoc-members:
\ No newline at end of file
+ :undoc-members:
diff --git a/docs/classes/ALL_Functions.rst b/docs/classes/ALL_Functions.rst
index 2be459b..4e72896 100644
--- a/docs/classes/ALL_Functions.rst
+++ b/docs/classes/ALL_Functions.rst
@@ -2,6 +2,6 @@
ALL_Functions overview
======================
-.. doxygennamespace:: ALL_Functions
+.. doxygennamespace:: ALL::Functions
:project: ALL
diff --git a/docs/classes/ALL_Histogram.rst b/docs/classes/ALL_Histogram.rst
index 0c5dcbb..8e2fafa 100644
--- a/docs/classes/ALL_Histogram.rst
+++ b/docs/classes/ALL_Histogram.rst
@@ -2,7 +2,7 @@
ALL_Histogram
=============
-.. doxygenclass:: ALL_Histogram_LB
+.. doxygenclass:: ALL::Histogram_LB
:members:
:protected-members:
:private-members:
diff --git a/docs/classes/ALL_LB.rst b/docs/classes/ALL_LB.rst
index 161213f..d065513 100644
--- a/docs/classes/ALL_LB.rst
+++ b/docs/classes/ALL_LB.rst
@@ -2,8 +2,8 @@
ALL_LB
=============
-.. doxygenclass:: ALL_LB
+.. doxygenclass:: ALL::LB
:members:
:protected-members:
:private-members:
- :undoc-members:
\ No newline at end of file
+ :undoc-members:
diff --git a/docs/classes/ALL_Point.rst b/docs/classes/ALL_Point.rst
index 811bc90..76a95c0 100644
--- a/docs/classes/ALL_Point.rst
+++ b/docs/classes/ALL_Point.rst
@@ -2,8 +2,8 @@
ALL_Point
=============
-.. doxygenclass:: ALL_Point
+.. doxygenclass:: ALL::Point
:members:
:protected-members:
:private-members:
- :undoc-members:
\ No newline at end of file
+ :undoc-members:
diff --git a/docs/classes/ALL_Staggered.rst b/docs/classes/ALL_Staggered.rst
index 4ee2c69..2889690 100644
--- a/docs/classes/ALL_Staggered.rst
+++ b/docs/classes/ALL_Staggered.rst
@@ -2,7 +2,7 @@
ALL_Staggered
=============
-.. doxygenclass:: ALL_Staggered_LB
+.. doxygenclass:: ALL::Staggered_LB
:members:
:protected-members:
:private-members:
diff --git a/docs/classes/ALL_Tensor.rst b/docs/classes/ALL_Tensor.rst
index 615fd49..5386fc0 100644
--- a/docs/classes/ALL_Tensor.rst
+++ b/docs/classes/ALL_Tensor.rst
@@ -2,8 +2,8 @@
ALL_Tensor
==========
-.. doxygenclass:: ALL_Tensor_LB
+.. doxygenclass:: ALL::Tensor_LB
:members:
:private-members:
:protected-members:
- :undoc-members:
\ No newline at end of file
+ :undoc-members:
diff --git a/docs/classes/ALL_Voronoi.rst b/docs/classes/ALL_Voronoi.rst
new file mode 100644
index 0000000..03bd940
--- /dev/null
+++ b/docs/classes/ALL_Voronoi.rst
@@ -0,0 +1,9 @@
+===========
+ALL_Voronoi
+===========
+
+.. doxygenclass:: ALL::Voronoi_LB
+ :members:
+ :private-members:
+ :protected-members:
+ :undoc-members:
--
GitLab