Skip to content
GitLab
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
Expand all Hide whitespace changes
Inline Side-by-side
.gitlab-ci.yml
View file @ 1173df06
......@@ -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
......
CMakeLists.txt
View file @ 1173df06
......@@ -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)
......
README.md 0 → 100644
View file @ 1173df06
# 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/
doc/Doxyfile.in 0 → 100644
View file @ 1173df06
This diff is collapsed.
doc/DoxygenLayout.xml 0 → 100644
View file @ 1173df06
<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>
doc/conf.py 0 → 100644
View file @ 1173df06
# -- 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__"]
doc/index.rst 0 → 100644
View file @ 1173df06
=========================
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
psrdada_cpp/dada_db.hpp
View file @ 1173df06
......@@ -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
......
psrdada_cpp/dada_read_client.hpp
View file @ 1173df06
......@@ -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.
*/
......
psrdada_cpp/dada_write_client.hpp
View file @ 1173df06
......@@ -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);
......
psrdada_cpp/double_buffer.cuh
View file @ 1173df06
......@@ -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.
*
......
psrdada_cpp/effelsberg/edd/EDDPolnMerge.hpp
View file @ 1173df06
......@@ -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.
......
psrdada_cpp/effelsberg/edd/EDDRoach.hpp
View file @ 1173df06
......@@ -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.
......
psrdada_cpp/effelsberg/edd/EDDRoach_merge.hpp
View file @ 1173df06
......@@ -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.
......
psrdada_cpp/effelsberg/edd/FftSpectrometer.cuh
View file @ 1173df06
......@@ -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