Commit 1173df06 authored by Tobias Winchen's avatar Tobias Winchen
Browse files

Merge branch 'doc' into 'devel'

Add initial documentation setup

See merge request !2
parents 5aa306fa 9f05921f
Pipeline #87635 canceled with stages
in 45 seconds
......@@ -3,12 +3,21 @@ stages:
- test
- deploy
image: edd01:5000/eddbase:latest
image: edd01:5000/eddbase
variables:
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
cache:
paths:
- .cache/pip
- .cache/apt
before_script:
- git submodule init
- git submodule update
- apt-get -y update && apt-get install -y python3-pip python3-graphviz doxygen
- pip3 install sphinx sphinxcontrib-apidoc sphinx-rtd-theme recommonmark \
sphinxcontrib-napoleon sphinx-autoapi breathe exhale
build_cuda:
stage: build
......@@ -21,14 +30,36 @@ build_cuda:
paths:
- build
run_tests:
stage: test
script:
- cd build
- make CTEST_OUTPUT_ON_FAILURE=1 test
make_doc:
stage: test
script:
- cd build
- make doc
artifacts:
paths:
- build
pages:
stage: deploy
dependencies:
- make_doc
script:
- mkdir public
- mv build/doc/* public/
artifacts:
paths:
- public
only:
- dev@mpifr-bdg/psrdada_cpp
- cicd@mpifr-bdg/psrdada_cpp
- doc@mpifr-bdg/psrdada_cpp
......
......@@ -37,6 +37,40 @@ include(dependencies)
add_subdirectory(${CMAKE_PROJECT_NAME})
# ------------------------------------------------------------------
# Documentation
# ------------------------------------------------------------------
find_package(Doxygen)
find_program(SPHINX_EXECUTABLE
NAMES sphinx-build
DOC "Path to sphinx-build executable")
if(DOXYGEN_FOUND AND SPHINX_EXECUTABLE)
MESSAGE(STATUS "Found Doxygen and Sphinx to build documentation")
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doc/DoxygenLayout.xml ${CMAKE_CURRENT_BINARY_DIR}/DoxygenLayout.xml COPYONLY)
# configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doc/Mainpage.md.in ${CMAKE_CURRENT_BINARY_DIR}/Mainpage.md)
add_custom_target(doxy ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating API documentation with Doxygen" VERBATIM)
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Sphinx
"Failed to find sphinx-build executable"
SPHINX_EXECUTABLE)
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/doc)
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/doc)
add_custom_target(doc
${SPHINX_EXECUTABLE} -b html
-Dbreathe_projects.psrdada-cpp=${CMAKE_CURRENT_BINARY_DIR}/xml
${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating documentation with Sphinx")
add_dependencies(doc doxy)
else()
MESSAGE(STATUS "Doxygen and Sphinx not found: cannot build documentation")
endif(DOXYGEN_FOUND AND SPHINX_EXECUTABLE)
# === Print build options summary.
set(DEBUG_PRINT ON)
......
# psrdada-cpp
psrdada-cpp provides C++ wrappers for a subset for PSRDADA functionality (HDUs,
read/write clients, etc.) and data processing pipelines build with them.
The documentation of psrdadad-cpp can be found at: http://mpifr-bdg.pages.mpcdf.de/psrdada_cpp/
This diff is collapsed.
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.8.13 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="Building Blocks" intro="Here is a list of CRPropa code grouped by features"/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<classes visible="yes" title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a file page -->
<file>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="$INCLUDE_GRAPH"/>
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
<sourcelink visible="yes"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="$GROUP_GRAPHS"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>
# -- Project information -----------------------------------------------------
project = u'psrdada-cpp'
copyright = u'2020, The psrdada-cpp Developers'
author = u'The psrdada-cpp Developers'
# The short X.Y version
version = u''
# The full version, including alpha/beta/rc tags
release = u''
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# 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',
'sphinx.ext.doctest',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
"breathe",
"exhale",
# "m2r",
# "nbsphinx"
]
# Breathe Configuration
breathe_default_project = "psrdada-cpp"
breathe_domain_by_extension = {"h" : "cpp", "cuh": "cu"}
#source_parsers = {
# '.md': 'recommonmark.parser.CommonMarkParser',
#}
# Add any paths that contain templates here, relative to this directory.
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'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# 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 = {
'collapse_navigation': False,
'canonical_url': "",
'logo_only': True,
'display_version': False,
}
html_show_sourcelink = False
html_logo = ""
# 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_js_files = [
# 'js/breathe_fold.js',
#]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'psrdadacpp3doc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
exhale_args = {
# These arguments are required
"containmentFolder": "./_api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API",
"doxygenStripFromPath": "..",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": False,
}
# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'
# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'
cpp_id_attributes = ["__global__", "__device__", "__forceinline__", "__restrict__"]
=========================
PSRDADA-CPP Documentation
=========================
psrdada-cpp provides C++ wrappers for a subset for `PSRDADA
<http://psrdada.sourceforge.net/>` functionality (HDUs, read/write clients,
etc.) and data processing pipelines build with them.
Contents
========
.. toctree::
:caption: API
:maxdepth: 2
_api/library_root
.. toctree::
:caption: DEVEL
:maxdepth: 1
......@@ -69,7 +69,7 @@ class DadaDB
/**
* @brief Return the hexidecimal shared memory key
*
* @detail This key can be used by other processes to access
* @details This key can be used by other processes to access
* the shared memory blocks.
*
* @note This key is the key to the data blocks. To access
......
......@@ -33,7 +33,7 @@ namespace psrdada_cpp {
/**
* @brief Get the next header block in the ring buffer
*
* @detail As only one block can be open at a time, release() must
* @details As only one block can be open at a time, release() must
* be called between subsequenct next() calls.
*
* @return A RawBytes instance wrapping a pointer to share memory
......@@ -43,7 +43,7 @@ namespace psrdada_cpp {
/**
* @brief Release the current data block.
*
* @detail This will mark the block as cleared, making it
* @details This will mark the block as cleared, making it
* writeable by writing client.
*/
void release();
......@@ -56,7 +56,7 @@ namespace psrdada_cpp {
/**
* @brief Realease all full header blocks in the buffer
*
* @detail This method checks the number of full header
* @details This method checks the number of full header
* blocks then calls next() release() that number
* of times.
*/
......@@ -83,7 +83,7 @@ namespace psrdada_cpp {
/**
* @brief Get the next data block in the ring buffer
*
* @detail As only one block can be open at a time, release() must
* @details As only one block can be open at a time, release() must
* be called between subsequenct next() calls.
*
* @return A RawBytes instance wrapping a pointer to share memory
......@@ -93,7 +93,7 @@ namespace psrdada_cpp {
/**
* @brief Release the current data block.
*
* @detail This will mark the block as cleared, making it
* @details This will mark the block as cleared, making it
* writeable by writing client.
*/
void release();
......@@ -111,7 +111,7 @@ namespace psrdada_cpp {
/**
* @brief Realease all full data blocks in the buffer
*
* @detail This method checks the number of full data
* @details This method checks the number of full data
* blocks then calls next() release() that number
* of times.
*/
......
......@@ -38,7 +38,7 @@ namespace psrdada_cpp {
/**
* @brief Get the next header block in the ring buffer
*
* @detail As only one block can be open at a time, release() must
* @details As only one block can be open at a time, release() must
* be called between subsequenct next() calls.
*
* @return A RawBytes instance wrapping a pointer to share memory
......@@ -48,7 +48,7 @@ namespace psrdada_cpp {
/**
* @brief Release the current header block.
*
* @detail This will mark the block as filled, making it
* @details This will mark the block as filled, making it
* readable by reading client.
*/
void release();
......@@ -74,7 +74,7 @@ namespace psrdada_cpp {
/**
* @brief Get the next data block in the ring buffer
*
* @detail As only one block can be open at a time, release() must
* @details As only one block can be open at a time, release() must
* be called between subsequenct next() calls.
*
* @return A RawBytes instance wrapping a pointer to share memory
......@@ -84,7 +84,7 @@ namespace psrdada_cpp {
/**
* @brief Release the current data block.
*
* @detail This will mark the block as filled, making it
* @details This will mark the block as filled, making it
* readable by reading client.
*/
void release(bool eod=false);
......
......@@ -8,7 +8,7 @@ namespace psrdada_cpp {
*
* @tparam T The internal data type for the buffers
*
* @detail An implementation of the double buffer concept
* @details An implementation of the double buffer concept
* using thrust::device_vector. Provides double
* buffers in GPU memory.
*
......
......@@ -19,7 +19,7 @@ public:
* @brief A callback to be called on connection
* to a ring buffer.
*
* @detail The first available header block in the
* @details The first available header block in the
* in the ring buffer is provided as an argument.
* It is here that header parameters could be read
* if desired.
......
......@@ -19,7 +19,7 @@ public:
* @brief A callback to be called on connection
* to a ring buffer.
*
* @detail The first available header block in the
* @details The first available header block in the
* in the ring buffer is provided as an argument.
* It is here that header parameters could be read
* if desired.
......
......@@ -19,7 +19,7 @@ public:
* @brief A callback to be called on connection
* to a ring buffer.
*
* @detail The first available header block in the
* @details The first available header block in the
* in the ring buffer is provided as an argument.
* It is here that header parameters could be read
* if desired.
......
......@@ -38,7 +38,7 @@ public:
* @brief A callback to be called on connection
* to a ring buffer.
*
* @detail The first available header block in the