Commit b185c9aa authored by Swann Perarnau's avatar Swann Perarnau
Browse files

Merge branch 'sphinx-breathe' into 'master'

Initial conversion of documentation to sphinx+breathe for readthedocs

Closes #36

See merge request !49
parents 669a4f7e 6b9687d2
Pipeline #7005 passed with stages
in 6 minutes and 35 seconds
ACLOCAL_AMFLAGS = -I m4
SUBDIRS = src include tests
SUBDIRS = src include tests doc
if ADD_BENCHMARKS
SUBDIRS += benchmarks
endif
if AML_DOXYGEN
SUBDIRS += doc
endif
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = aml.pc
......
......@@ -69,11 +69,24 @@ AC_CHECK_HEADERS([numa.h],,[AC_MSG_ERROR([AML requires libnuma headers.])])
AC_CHECK_HEADERS([numaif.h],,[AC_MSG_ERROR([AML requires libnuma headers.])])
AC_CHECK_LIB(numa, mbind,,[AC_MSG_ERROR([AML requires libnuma.])])
# Doxygen
# See m4/ax_doxygen.m4
AC_CHECK_PROG(doxygen_happy, [doxygen], [yes], [no])
AM_CONDITIONAL([AML_DOXYGEN],[ test "x$doxygen_happy" = "xyes" ])
# check doxygen + sphinx for documentation build
AC_CHECK_PROG([DOXYGEN], [doxygen], [doxygen], [no])
AC_CHECK_PROG([SPHINXBUILD], [sphinx-build], [sphinx-build], [no])
if [[ "x$DOXYGEN" != xno ]]; then
if [[ "x$SPHINXBUILD" != xno ]]; then
AC_MSG_NOTICE([Doxygen and Sphinx found, documentation will be build])
BUILD_DOCS=yes
else
AC_MSG_NOTICE([Sphinx not found, cannot build documentation])
BUILD_DOCS=no
fi
else
AC_MSG_NOTICE([Doxygen not found, cannot build documentation])
BUILD_DOCS=no
fi
AM_CONDITIONAL([BUILD_DOCS],[ test "x$BUILD_DOCS" = xyes ])
AC_CONFIG_HEADERS([include/config.h])
......
......@@ -2,26 +2,31 @@ DATA_INSTALL_DIR=$(datadir)/aml
DOXYGEN_BUILD_DIR=./build-doxygen
SPHINX_BUILD_DIR=./build-sphinx
doxygen:
doxygen aml.doxy
if BUILD_DOCS
build-docs:
$(DOXYGEN) aml.doxy
$(SPHINXBUILD) -b html -a . $(SPHINX_BUILD_DIR)
else
build-docs:
echo "not building documentation"
endif
create-doc-dir:
mkdir -p $(DATA_INSTALL_DIR)
install-doc-html:
if [ -d $(DOXYGEN_BUILD_DIR)/html ]; then \
cp -r $(DOXYGEN_BUILD_DIR)/html $(DATA_INSTALL_DIR); \
install-doc-html: build-docs
if [ -d $(SPHINX_BUILD_DIR) ]; then \
cp -r $(SPHINX_BUILD_DIR) $(DATA_INSTALL_DIR)/html; \
fi
install-data-local: create-doc-dir install-doc-html
uninstall-local:
rm -rf $(DATA_INSTALL_DIR)
clean-local:
rm -rf $(DOXYGEN_BUILD_DIR) $(SPHINX_BUILD_DIR)
dist-hook: doxygen
cp -r $(DOXYGEN_BUILD_DIR) $(distdir)
dist-hook: build-docs
cp -r $(SPHINX_BUILD_DIR) $(distdir)
EXTRA_DIST= aml.doxy conf.py pages index.rst img
......@@ -794,8 +794,8 @@ INPUT = ../include \
../include/aml/area \
../include/aml/tiling \
../include/aml/dma \
../include/aml/scratch \
../include/aml/utils \
md \
../CONTRIBUTING.markdown
img/building-blocks-diagram.png
......@@ -1953,7 +1953,7 @@ MAN_LINKS = NO
# captures the structure of the code including all documentation.
# The default value is: NO.
GENERATE_XML = NO
GENERATE_XML = YES
# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
......
......@@ -24,8 +24,10 @@ import os
import sys
import subprocess
# Generate documentation
subprocess.call('doxygen aml.doxy', shell=True)
# Generate doxygen first if in read the docs.
read_the_docs = os.environ.get('READTHEDOCS', None) == 'True'
if read_the_docs:
subprocess.call('doxygen aml.doxy', shell=True)
# -- General configuration ---------------------------------------------------
......@@ -35,7 +37,7 @@ language = 'C'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
extensions = ["breathe", "recommonmark"]
# Add any paths that contain templates here, relative to this directory.
templates_path = []
......@@ -45,25 +47,32 @@ templates_path = []
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# ensure that the master file is index.
# mostly needed because the sphinx version on RTD expects a contents.rst
# instead.
master_doc = 'index'
# -- Project information -----------------------------------------------------
project = 'AML'
copyright = 'Copyright 2019 UChicago Argonne, LLC'
author = 'Swann Perarnau, Kamil Iskra, Brian Suchy, Valentin Reis, Nicolas Denoyelle'
release = 'X.X.X'
release = '0.1.0'
# -- 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 = 'alabaster'
if read_the_docs:
html_theme = 'default'
else:
html_theme = "sphinx_rtd_theme"
# 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 = []
#Overwrite sphinx documentation with doxygen documentation.
html_extra_path = ['build-doxygen/html']
breathe_projects = {"aml": "build-doxygen/xml"}
breathe_default_project = "aml"
This is an empty file required by shpinx when
compiling documentation on readthedocs.org.
This is an empty landing page overwritten with doxygen documentation.
AML: Building Blocks for Explicit Memory Management
===================================================
AML is a memory management library designed to ease the use of complex memory
topologies and complex data layout optimizations for high-performance computing
applications.
AML is Open Source, distributed under the BSD 3 clause license.
Overview
--------
AML is a framework providing locality-preserving abstractions to application
developers. In particular, AML aims to expose flexible interfaces to describe
and reason about how applications deal with data layout, tiling of data,
placement of data across hardware topologies, and affinity between work and
data.
AML is organized as a collection of abstractions, presented as *building
blocks*, to develop explicit memory and data management policies. AML goals
are:
* **composability**: application developers and performance experts should be
to pick and choose which building blocks to use depending on their specific
needs.
* **flexibility**: users should be able to customize, replace, or change the
configuration of each building block as much as possible.
As of now, AML implements the following abstractions:
.. image:: img/building-blocks-diagram.png
:width: 300px
:align: right
* :doc:`Areas <pages/areas>`, a set of addressable physical memories,
* :doc:`Tilings <pages/tilings>`, a description of tiling data structures,
* :doc:`DMAs <pages/dmas>`, an engine to asynchronously move data structures between areas,
* :doc:`Scratchpads <pages/scratchs>`, a stage-in, stage-out abstraction for prefetching.
Each of these abstractions have several implementations. For instance, areas
may refer to usual DRAM or a subset of them, GPU memory or non-volatile memory.
Tilings are implemented to reflect either 1D or 2D structures and so on.
Quick Start Guide
-----------------
Download
~~~~~~~~
* `Development version <https://xgitlab.cels.anl.gov/argo/aml>`_:
.. code-block:: console
$ git clone git@xgitlab.cels.anl.gov:argo/aml.git
Requirements:
~~~~~~~~~~~~~
* autoconf
* automake
* libtool
* libnuma
Installation
~~~~~~~~~~~~
.. code-block:: console
$ sh autogen.sh
$ ./configure
$ make -j install
Workflow
~~~~~~~~
Include aml header:
.. code-block:: c
#include <aml.h>
...
int main(int argc, char **argv){
Check AML version:
.. code-block:: c
if(aml_version_major != AML_VERSION_MAJOR){
printf("AML ABI mismatch!");
return 1;
}
Initialize and Cleanup AML:
.. code-block:: c
if(aml_init(&argc, &argv) != 0){
printf("AML library init failure!");
return 1;
}
...
aml_finalize();
Link your program with *-laml*.
See above building blocks specific pages for further examples and information
on library features.
Support
-------
Support for AML is provided through the
`gitlab issue interface <https://xgitlab.cels.anl.gov/argo/aml/issues>`_.
Alternatively you can contact directly the developers/maintainers:
* Swann Perarnau (swann AT anl DOT gov)
* Nicolas Denoyelle (ndenoyelle AT anl DOT gov)
Contributing
------------
AML welcomes any comment, suggestion, bug reporting, or feature request, as
well as code contributions. See the [contributing page](@ref contributing_page)
for more info.
.. toctree::
:maxdepth: 2
pages/areas
pages/tilings
pages/dmas
pages/scratchs
Welcome to AML Documentation Page {#index}
============
AML is a memory management library designed to ease the use of complex memory
topologies and complex data layout optimizations for high-performance computing
applications.
AML is Open Source, distributed under the BSD 3 clause license.
## Overview
AML is a framework providing locality-preserving abstractions to application
developers. In particular, AML aims to expose flexible interfaces to describe
and reason about how applications deal with data layout, tiling of data,
placement of data across hardware topologies, and affinity between work and
data.
AML is organized as a collection of abstractions, presented as *building
blocks*, to develop explicit memory and data management policies. AML goals
are:
* __composability__: application developers and performance experts should be
to pick and choose which building blocks to use depending on their specific
needs.
* __flexibility__: users should be able to customize, replace, or change the
configuration of each building block as much as possible.
As of now, AML implements the following abstractions:
\image html building-blocks-diagram.png width=400cm
* [Areas](@ref aml_area), a set of addressable physical memories,
* [Tilings](@ref aml_tiling), a description of tiling data structures,
* [DMA](@ref aml_dma), an engine to asynchronously move data structures between areas,
* [Scratchpad](@ref aml_scratch), a stage-in, stage-out abstraction for prefetching.
Each of these abstractions have several implementations. For instance, areas
may refer to usual DRAM or a subset of them, GPU memory or non-volatile memory.
Tilings are implemented to reflect either 1D or 2D structures and so on.
## Quick Start Guide
### Download
* [Development version](https://xgitlab.cels.anl.gov/argo/aml):
```
git clone git@xgitlab.cels.anl.gov:argo/aml.git
```
* Release versions:
TODO after release.
### Requirements:
* autoconf
* automake
* libtool
* libnuma
### Installation
```
sh autogen.sh
./configure
make -j install
```
### Workflow
* Include aml header:
```
#include <aml.h>
...
int main(int argc, char **argv){
```
* Check AML version:
```
if(aml_version_major != AML_VERSION_MAJOR){
printf("AML ABI mismatch!");
return 1;
}
```
* Initialize and Cleanup AML:
```
if(aml_init(&argc, &argv) != 0){
printf("AML library init failure!");
return 1;
}
...
aml_finalize();
```
* Link your program with `-laml`
See above building blocks specific pages for further examples and information
on library features.
## Support
Support for AML is provided through the
[gitlab issue interface](https://xgitlab.cels.anl.gov/argo/aml/issues).
Alternatively you can contact directly the developers/maintainers:
* Swann Perarnau (swann AT anl DOT gov)
* Nicolas Denoyelle (ndenoyelle AT anl DOT gov)
## Contributing
AML welcomes any comment, suggestion, bug reporting, or feature request, as
well as code contributions. See the [contributing page](@ref contributing_page)
for more info.
Area Linux Implementation API
=================================
.. doxygengroup:: aml_area_linux
Areas: Addressable Physical Memories
====================================
.. doxygengroup:: aml_area
Implementations
---------------
.. toctree::
area_linux_api
DMA Linux Parallel Implementation API
=====================================
.. doxygengroup:: aml_dma_linux_par
DMA Linux Sequential Implementation API
=======================================
.. doxygengroup:: aml_dma_linux_seq
DMAs: Moving Data Across Areas
====================================
.. doxygengroup:: aml_dma
Implementations
---------------
.. toctree::
dma_linux_seq_api
dma_linux_par_api
Scratchpad Parallel Implementation API
======================================
.. doxygengroup:: aml_scratch_par
Scratchpad Sequential Implementation API
========================================
.. doxygengroup:: aml_scratch_seq
Scratchpads: Staging in and out data
====================================
.. doxygengroup:: aml_scratch
Implementations
---------------
.. toctree::
scratch_seq_api
scratch_par_api
Tiling 1D Implementation API
============================
.. doxygengroup:: aml_tiling_1d
Tiling 2D Implementation API
============================
.. doxygengroup:: aml_tiling_2d
Tilings: Decomposing Data
====================================
.. doxygengroup:: aml_tiling
Implementations
---------------
.. toctree::
tiling_1d_api
tiling_2d_api
......@@ -307,51 +307,6 @@ struct aml_tiling {
struct aml_tiling_data *data;
};
/**
Allocates and initializes a new tiling.
* @param tiling: an address where the pointer to the newly allocated tiling
* structure will be stored.
* @param type: see AML_TILING_TYPE_*.
* If "type" equals AML_TILING_TYPE_1D, two additional arguments are
* needed: tilesize, totalsize.
* If "type" equals AML_TILING_TYPE_2D, four additional arguments are
* needed: tilesize, totalsize, rowsize, colsize.
* @param tilesize: an argument of type size_t; provides the size of a tile.
* @param totalsize: an argument of type size_t; provides the size of the
* complete user data structure to be tiled.
* @param rowsize: an argument of type size_t; the number of tiles in a row
* @param colsize: an argument of type size_t; the number of tiles in a column
* @return 0 if successful; an error code otherwise.
**/
int aml_tiling_create(struct aml_tiling **tiling, int type, ...);
/**
* Initializes a tiling. This is a varargs-variant of the aml_tiling_vinit()
* routine.
* @param tiling: an allocated tiling structure.
* @param type: see aml_tiling_create().
* Variadic arguments: see aml_tiling_create().
* @return 0 if successful; an error code otherwise.
**/
int aml_tiling_init(struct aml_tiling *tiling, int type, ...);
/**
* Initializes a tiling.
* @param tiling: an allocated tiling structure.
* @param type: see aml_tiling_create().
* @param args: see the variadic arguments of aml_tiling_create().
* @return 0 if successful; an error code otherwise.
**/
int aml_tiling_vinit(struct aml_tiling *tiling, int type, va_list args);
/**
* Tears down an initialized tiling.
* @param tiling: an initialized tiling structure.
* @param type: see aml_tiling_create().
* @return 0 if successful; an error code otherwise.
**/
int aml_tiling_destroy(struct aml_tiling *tiling, int type);
/**
* Provides the tile id of a tile.
* @param tiling: an initialized tiling structure.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment