WIP: Tryout sphinx

.readthedocs.yaml

@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - doxygen
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: doc/requirements.txt

doc/CMakeLists.txt

@@ -9,7 +9,7 @@ if(GINKGO_DOC_GENERATE_EXAMPLES)
     add_subdirectory(examples)
 endif()
 
-set(default_predefined_macros "GKO_HAVE_PAPI_SDE=1 GINKGO_BUILD_MPI=1")
+set(default_predefined_macros "GKO_HAVE_PAPI_SDE=1 GINKGO_BUILD_MPI=1 GINKGO_BUILD_DOXYGEN=1")
 
 if (GINKGO_DOC_GENERATE_PDF)
     find_package(LATEX COMPONENTS PDFLATEX REQUIRED)

doc/api.rst

@@ -0,0 +1,9 @@
+Full API Reference
+==================
+
+.. toctree::
+  :maxdepth: 3
+
+  api/linop
+  api/matrix
+  api/types

doc/api/linop.rst

@@ -0,0 +1,9 @@
+LinOp
+=====
+
+
+.. doxygenclass:: gko::LinOp
+  :private-members:
+
+.. doxygenclass:: gko::EnableLinOp
+  :private-members:

doc/api/matrix.rst

@@ -0,0 +1,8 @@
+Matrices
+========
+
+.. doxygenclass:: gko::matrix::Coo
+
+An example on how to use a Coo matrix.
+
+.. doxygenclass:: gko::matrix::Csr

doc/api/types.rst

@@ -0,0 +1,7 @@
+Type Definitions
+================
+
+
+.. doxygenfile:: types.hpp
+  :sections: typedef var enum define innernamespace
+

doc/conf.py

@@ -0,0 +1,164 @@
+# 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
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Ginkgo'
+copyright = '2023, Marcel Koch'
+author = 'Ginkgo Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['breathe', 'sphinx.ext.duration', 'sphinx.ext.autosummary']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'c++'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Options for C++ domain
+
+cpp_index_common_prefix = ['gko::']
+
+# -- Options for Doxygen
+
+ginkgo_root = Path('..').resolve()
+ginkgo_include = Path('../include').resolve()
+doxygen_dir = Path('doxygen').resolve()
+
+doxyfile = f"""
+QUIET                  = YES
+
+# General project info
+PROJECT_NAME           = "Ginkgo"
+PROJECT_NUMBER         = "Generated from document-create-functions branch based on develop. Ginkgo version 1.7.0 "
+PROJECT_BRIEF          = "A numerical linear algebra library targeting many-core architectures"
+INLINE_INHERITED_MEMB  = YES
+
+# Paths and in/exclusion patterns
+#The INPUT variable is defined in the specific doxy files for usr and dev.
+INPUT                  =
+
+INCLUDE_PATH           = {ginkgo_include} {ginkgo_root}
+OUTPUT_DIRECTORY       = {doxygen_dir}
+EXAMPLE_PATH           = 
+RECURSIVE              = YES
+EXAMPLE_RECURSIVE      = NO
+FILE_PATTERNS          = *.cpp *.cu *.hpp *.cuh *.md
+EXAMPLE_PATTERNS       = *.cpp *.hpp *.cuh *.cu
+EXTENSION_MAPPING      = cu=c++ cuh=c++
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = {ginkgo_include}
+STRIP_FROM_INC_PATH    = {ginkgo_include}
+EXCLUDE_PATTERNS       = */test/*
+PROJECT_LOGO           = {ginkgo_root}/assets/logo_doc.png
+USE_MDFILE_AS_MAINPAGE = 
+FILTER_PATTERNS        = *.cpp={ginkgo_root}/doc/scripts/filter *.hpp={ginkgo_root}/doc/scripts/filter *.cu*={ginkgo_root}/doc/scripts/filter
+FILTER_SOURCE_FILES    = YES
+
+# Parsing options
+PREDEFINED             = GKO_HAVE_PAPI_SDE=1 GINKGO_BUILD_MPI=1 GINKGO_BUILD_DOXYGEN=1
+JAVADOC_AUTOBRIEF      = Yes
+TAB_SIZE               = 4
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+MACRO_EXPANSION        = YES
+SKIP_FUNCTION_MACROS   = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = NO
+GENERATE_TESTLIST      = NO
+GENERATE_BUGLIST       = NO
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+CITE_BIB_FILES         =
+INHERIT_DOCS           = YES
+USE_MATHJAX            = NO
+
+BUILTIN_STL_SUPPORT    = YES
+
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = NO
+WARNINGS               = YES
+IMAGE_PATH             = 
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+VERBATIM_HEADERS       = YES
+# CLANG_ASSISTED_PARSING = NO
+# CLANG_OPTIONS          = -I{ginkgo_root} -std=c++14
+
+# External references
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+
+# Graph generation
+
+GENERATE_XML             = YES
+
+# this is used to hide protected members
+PREDEFINED = GKO_HAVE_PAPI_SDE=1 GINKGO_BUILD_MPI=1 GINKGO_BUILD_DOXYGEN=1 protected=private
+
+INPUT = {ginkgo_include} 
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_PRIVATE        = YES
+INTERNAL_DOCS          = YES
+SOURCE_BROWSER         = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+EXCLUDE_SYMBOLS        = *detail::* std::*
+WARN_LOGFILE           = 
+# These are the LaTeX packages we use
+EXTRA_PACKAGES         = mathtools amsfonts amsmath amssymb
+"""
+
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+if read_the_docs_build:
+    subprocess.run(['doxygen', '-'], input=doxyfile, universal_newlines=True)
+    xml_dir = f"{doxygen_dir}/xml"
+else:
+    pass
+
+# -- Options for breathe
+
+breathe_projects = {
+    "ginkgo-doxy": f"{doxygen_dir}/xml"}
+breathe_default_project = "ginkgo-doxy"
+breathe_default_members = ("members", "undoc-members")
+breathe_order_parameters_first = True
+breathe_show_include = True

doc/conf/Doxyfile-usr.in

@@ -1,4 +1,5 @@
-GENERATE_HTML          = YES
+# GENERATE_HTML          = YES
+GENERATE_XML             = YES
 
 # this is used to hide protected members
 PREDEFINED = @default_predefined_macros@ protected=private

doc/conf/Doxyfile.in

@@ -82,19 +82,19 @@ ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 
 # Graph generation
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
+CLASS_GRAPH            = NO
+COLLABORATION_GRAPH    = NO
+GROUP_GRAPHS           = NO
+GRAPHICAL_HIERARCHY    = NO
+DIRECTORY_GRAPH        = NO
 DOT_IMAGE_FORMAT       = svg
-INTERACTIVE_SVG        = YES
-GENERATE_LEGEND        = YES
-HAVE_DOT               = YES
+INTERACTIVE_SVG        = NO
+GENERATE_LEGEND        = NO
+HAVE_DOT               = NO
 DOTFILE_DIRS           = @DIR_BASE@/doc/headers
 TEMPLATE_RELATIONS     = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
 MAX_DOT_GRAPH_DEPTH    = 5
 
 DOT_CLEANUP            = YES

doc/index.rst

@@ -0,0 +1,27 @@
+.. ginkgo documentation master file, created by
+   sphinx-quickstart on Mon Jul 31 14:33:24 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Ginkgo's documentation!
+==================================
+
+Documentation of the Ginkgo library.
+
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Contents:
+
+  user_guide
+  api
+
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/requirements.txt

@@ -0,0 +1,2 @@
+breathe>=4.35.0
+sphinx-rtd-theme