Skip to content
Snippets Groups Projects
Commit 19a0c964 authored by Stephan Schulz's avatar Stephan Schulz
Browse files

update sphinx documentation (#31)

parent 0330d054
Branches
Tags
1 merge request!8Refactor
...@@ -17,6 +17,7 @@ find_package(Sphinx REQUIRED) ...@@ -17,6 +17,7 @@ find_package(Sphinx REQUIRED)
#if(NOT ${BREATHE_NOT_FOUND} EQUAL 0) #if(NOT ${BREATHE_NOT_FOUND} EQUAL 0)
# message( FATAL_ERROR "Python \"breathe\" package not found") # message( FATAL_ERROR "Python \"breathe\" package not found")
#endif() #endif()
# todo(s.schulz): Also find recommonmark
#do we need to make sure sphinx_rtd_theme is installed? #do we need to make sure sphinx_rtd_theme is installed?
# Find all public headers # Find all public headers
...@@ -37,10 +38,6 @@ set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md) ...@@ -37,10 +38,6 @@ set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md)
# configure doxygen config file # configure doxygen config file
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
set(SPHINX_IN ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
set(SPHINX_OUT ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
configure_file(${SPHINX_IN} ${SPHINX_OUT} @ONLY)
# create doxygen output directory # create doxygen output directory
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
...@@ -60,11 +57,16 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}) ...@@ -60,11 +57,16 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx) set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html) set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
set(SPHINX_IN ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
set(SPHINX_OUT ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
set(SPHINX_BREATHE_PROJECT_PATH ${DOXYGEN_OUTPUT_DIR}/xml)
configure_file(${SPHINX_IN} ${SPHINX_OUT} @ONLY)
# todo(s.schulz): Add dependencies to all .rst files
add_custom_command(OUTPUT ${SPHINX_INDEX_FILE} add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
COMMAND COMMAND
${SPHINX_EXECUTABLE} -b html ${SPHINX_EXECUTABLE} -b html
-Dbreathe_projects.ALL=${DOXYGEN_OUTPUT_DIR}/xml
-c "${CMAKE_CURRENT_BINARY_DIR}" -c "${CMAKE_CURRENT_BINARY_DIR}"
${SPHINX_SOURCE} ${SPHINX_BUILD} ${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
......
.. _ALLClass:
ALL class
=========
.. doxygenclass:: ALL::ALL
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
.. _PointClass:
Point class
===========
.. doxygenclass:: ALL::Point
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
.. _ALLModule:
ALL Fortran module
==================
Due to the case insensitive nature of Fortran and the used toolchain
(doxygen and sphinx), all variables and function names are lowercase on
this page. We do, however, use only upper case for global constants, such
as the load balancing methods (``ALL_STAGGERED`` etc.) and the function
names are usually written similarly to MPI as ``ALL_get_work``. The object
is of ``type(ALL_t)``.
Methods
-------
Available methods are:
.. doxygenvariable:: all_histogram
.. doxygenvariable:: all_staggered
.. doxygenvariable:: all_tensor
.. doxygenvariable:: all_unstructured
.. doxygenvariable:: all_voronoi
Errors
------
The exceptions map to the following error constants:
.. doxygenvariable:: all_error_filesystem
.. doxygenvariable:: all_error_generic
.. doxygenvariable:: all_error_internal
.. doxygenvariable:: all_error_invalidargument
.. doxygenvariable:: all_error_invalidcommtype
.. doxygenvariable:: all_error_outofbounds
.. doxygenvariable:: all_error_pointdimensionmissmatch
And the error message is returned in a string of length
``ALL_ERROR_LENGTH``.
Functions
---------
These function all have a corresponding call in the object, with the
``ALL_`` stripped from the function name. So with an object named
``balancer`` the function ``ALL_get_work(balancer, work)`` is identical to
``balancer%get_work(work)``. The following functions are available:
.. doxygenfunction:: all_balance
.. doxygenfunction:: all_finalize
.. doxygenfunction:: all_setup
Getters
*******
.. doxygenfunction:: all_get_dimension
.. doxygenfunction:: all_get_gamma
.. doxygenfunction:: all_get_length_of_work
.. doxygenfunction:: all_get_neighbors
.. doxygenfunction:: all_get_number_of_neighbors
.. doxygenfunction:: all_get_number_of_vertices
.. doxygenfunction:: all_get_prev_vertices
.. doxygenfunction:: all_get_vertices
.. doxygenfunction:: all_get_vertices_alloc
.. doxygenfunction:: all_get_work
.. doxygenfunction:: all_get_work_array
Setters
*******
.. doxygenfunction:: all_set_gamma
.. doxygenfunction:: all_set_method_data_histgram
.. doxygenfunction:: all_set_min_domain_size
.. doxygenfunction:: all_set_proc_grid_params
.. doxygenfunction:: all_set_proc_tag
.. doxygenfunction:: all_set_sys_size
.. doxygenfunction:: all_set_vertices
.. doxygenfunction:: all_set_work
.. doxygenfunction:: all_set_work_multi
Output
******
.. doxygenfunction:: all_print_vtk_outlines
.. doxygenfunction:: all_print_vtk_vertices
Error handling
**************
.. doxygenfunction:: all_error
.. doxygenfunction:: all_error_description
.. doxygenfunction:: all_reset_error
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
.. _CustomExceptions:
Custom Exceptions
=================
The library may throw one of these exceptions, which are all based on
``ALL::CustomException``.
``CustomException``
-------------------
.. doxygenstruct:: ALL::CustomException
:outline:
``FilesystemErrorException``
****************************
.. doxygenstruct:: ALL::FilesystemErrorException
:outline:
``InternalErrorException``
****************************
.. doxygenstruct:: ALL::InternalErrorException
:outline:
``InvalidArgumentException``
****************************
.. doxygenstruct:: ALL::InvalidArgumentException
:outline:
``InvalidCommTypeException``
****************************
.. doxygenstruct:: ALL::InvalidCommTypeException
:outline:
``OutOfBoundsException``
****************************
.. doxygenstruct:: ALL::OutOfBoundsException
:outline:
``PointDimensionMissmatchException``
****************************
.. doxygenstruct:: ALL::PointDimensionMissmatchException
:outline:
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
Public API Reference
====================
.. toctree::
:maxdepth: 2
:caption: API
ALL.rst
CustomExceptions.rst
ALL_Point.rst
ALL_module.rst
These pages should give a short overview of the public API
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
===
ALL
===
.. doxygenclass:: ALL::ALL
:members:
:protected-members:
:private-members:
:undoc-members:
======================
ALL_Functions overview
======================
.. doxygennamespace:: ALL::Functions
:project: ALL
=============
ALL_Histogram
=============
.. doxygenclass:: ALL::Histogram_LB
:members:
:protected-members:
:private-members:
:undoc-members:
=============
ALL_LB
=============
.. doxygenclass:: ALL::LB
:members:
:protected-members:
:private-members:
:undoc-members:
=============
ALL_Point
=============
.. doxygenclass:: ALL::Point
:members:
:protected-members:
:private-members:
:undoc-members:
=============
ALL_Staggered
=============
.. doxygenclass:: ALL::Staggered_LB
:members:
:protected-members:
:private-members:
:undoc-members:
==========
ALL_Tensor
==========
.. doxygenclass:: ALL::Tensor_LB
:members:
:private-members:
:protected-members:
:undoc-members:
===========
ALL_Voronoi
===========
.. doxygenclass:: ALL::Voronoi_LB
:members:
:private-members:
:protected-members:
:undoc-members:
...@@ -13,13 +13,16 @@ ...@@ -13,13 +13,16 @@
# import os # import os
# import sys # import sys
# sys.path.insert(0, os.path.abspath('.')) # sys.path.insert(0, os.path.abspath('.'))
from recommonmark.parser import CommonMarkParser
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
project = 'ALL' project = '@PROJECT_NAME@'
copyright = '2020, Rene Halver, Forschungszentrum Juelich GmbH' copyright = '2020, Rene Halver, Forschungszentrum Juelich GmbH'
author = 'Rene Halver' author = 'Rene Halver'
version = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@'
release = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@'
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
...@@ -32,6 +35,9 @@ extensions = [ "breathe" ] ...@@ -32,6 +35,9 @@ extensions = [ "breathe" ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
source_parseres = { '.md': CommonMarkParser }
source_suffix = ['.rst', '.md']
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path. # This pattern also affects html_static_path and html_extra_path.
...@@ -50,5 +56,12 @@ html_theme = 'sphinx_rtd_theme' ...@@ -50,5 +56,12 @@ html_theme = 'sphinx_rtd_theme'
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] html_static_path = ['_static']
html_theme_options = {
'sticky_navigation': True,
'style_external_links': True,
}
# Breath Config # Breath Config
breathe_projects = {"ALL":"@SPHINX_BREATHE_PROJECT_PATH@"}
breathe_default_project = "ALL" breathe_default_project = "ALL"
breathe_default_members = ('members', 'undoc-members')
.. .. _classes/FullDocumentation
.. ==================
.. Full Documentation
.. ==================
.. .. doxygenindex::
\ No newline at end of file
...@@ -3,22 +3,16 @@ ...@@ -3,22 +3,16 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
Welcome to ALL auto generated documentation! Welcome to the documentation of ALL
============================================ ===================================
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents: :caption: Contents:
:glob:
classes/* api/index.rst
.. .. toctree:: todo(s.schulz): Link to doxygen documentation.
.. :maxdepth: 2
.. :caption: Full documentation:
.. :glob:
.. full/*
Indices and tables Indices and tables
================== ==================
...@@ -28,3 +22,4 @@ Indices and tables ...@@ -28,3 +22,4 @@ Indices and tables
.. * :ref:`modindex` .. * :ref:`modindex`
.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment