Commit 357b98dc authored by Swann Perarnau's avatar Swann Perarnau

[doc/ci] make docs a configure flags, test it

Add a configure option for building docs, and create a CI job that will
always run to validate it. Note that make install-data doesn't need
source builds, so the environment can be quite small.

This patch also fixes the uncovered issues, and make doc build fail on
warnings.
parent 001e59ea
......@@ -29,6 +29,26 @@ checkpatch:
- git ls-files *.c *.h | grep -v -e benchmarks >> .checkpatch.conf
- nix run -f "$ARGOPKGS" checkpatch --command checkpatch.pl
style:docs:
stage: style
except:
- /^wip.*/
- /^WIP.*/
tags:
- integration
script:
- |
nix-shell "$ARGOPKGS" -A aml-dist --arg aml-src ./. --run bash << EOF
./autogen.sh
mkdir build
./configure --prefix=`pwd`/build --enable-docs
make install-data
EOF
artifacts:
when: on_failure
paths:
- config.log
make:generic:
stage: build
except:
......@@ -93,9 +113,6 @@ make:knl:
readthedocs:
stage: docs
except:
- /^wip.*/
- /^WIP.*/
when: on_success
only:
- master
......
......@@ -86,21 +86,23 @@ AC_CHECK_LIB(numa, mbind,,[AC_MSG_ERROR([AML requires libnuma.])])
# 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
AC_ARG_ENABLE(docs,
[AS_HELP_STRING([--enable-docs],
[Generate full html documentation (default is no).])],
[docs=true],[docs=false])
if [[ "x$docs" = xtrue ]]; then
AC_CHECK_PROG([DOXYGEN], [doxygen], [doxygen], [no])
if [[ "x$DOXYGEN" == xno ]]; then
AC_MSG_ERROR([Doxygen not found])
fi
AC_CHECK_PROG([SPHINXBUILD], [sphinx-build], [sphinx-build], [no])
if [[ "x$SPHINXBUILD" == xno ]]; then
AC_MSG_ERROR([Sphinx not found])
fi
else
AC_MSG_NOTICE([Doxygen not found, cannot build documentation])
BUILD_DOCS=no
fi
AM_CONDITIONAL([BUILD_DOCS],[ test "x$BUILD_DOCS" = xyes ])
AM_CONDITIONAL([BUILD_DOCS],[ test "x$docs" == xtrue ])
# check nvidia compiler and libraries
#####################################
......
......@@ -5,7 +5,7 @@ SPHINX_BUILD_DIR=./build-sphinx
if BUILD_DOCS
build-docs:
$(DOXYGEN) aml.doxy
$(SPHINXBUILD) -b html -a . $(SPHINX_BUILD_DIR)
$(SPHINXBUILD) -v -W -b html -a . $(SPHINX_BUILD_DIR)
dist-hook: build-docs
cp -r $(SPHINX_BUILD_DIR) $(distdir)
......
......@@ -756,13 +756,13 @@ WARN_IF_DOC_ERROR = YES
# parameter documentation, but not about the absence of documentation.
# The default value is: NO.
WARN_NO_PARAMDOC = NO
WARN_NO_PARAMDOC = YES
# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.
WARN_AS_ERROR = NO
WARN_AS_ERROR = YES
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
......
......@@ -35,7 +35,7 @@ AML currently implements the following abstractions:
* :doc:`Area <pages/areas>`, a set of addressable physical memories,
* :doc:`Layout <pages/layout>`, a description of data structure organization,
* :doc:`Tiling <pages/tilings>`, (soon to be replaced),
* :doc:`Tiling <pages/tilings>`, a description of data blocking (decomposition)
* :doc:`DMA <pages/dmas>`, an engine to asynchronously move data structures between areas,
* :doc:`Scratchpad <pages/scratchs>`, a stage-in, stage-out abstraction for prefetching.
......
Tiling 1D Implementation API
============================
.. doxygengroup:: aml_tiling_1d
Tiling 2D Implementation API
============================
.. doxygengroup:: aml_tiling_2d
Tiling Padded Implementation API
================================
.. doxygengroup:: aml_tiling_pad
Tiling Resize Implementation API
================================
.. doxygengroup:: aml_tiling_resize
......@@ -8,5 +8,5 @@ Implementations
.. toctree::
tiling_1d_api
tiling_2d_api
tiling_resize_api
tiling_pad_api
This diff is collapsed.
......@@ -11,7 +11,9 @@
/**
* @defgroup aml_area_cuda "AML Cuda Areas"
* @brief Cuda Implementation of Areas.
* @code
* #include <aml/area/cuda.h>
* @endcode
*
* Cuda implementation of AML areas.
* This building block relies on Cuda implementation of
......
......@@ -23,7 +23,9 @@
* a default initialized area that can be used out-of-the-box with
* the abstract area API.
*
* @code
* #include <aml/area/linux.h>
* @endcode
* @{
**/
......@@ -114,7 +116,7 @@ int aml_area_linux_create(struct aml_area **area,
* Destroys (finalizes and frees resources) struct aml_area created by
* aml_area_linux_create().
*
* @param address of an initialized struct aml_area pointer, which will be
* @param area address of an initialized struct aml_area pointer, which will be
* reset to NULL on return from this call.
**/
void aml_area_linux_destroy(struct aml_area **area);
......
......@@ -59,7 +59,7 @@ struct aml_dma_linux_par_data {
};
/** Declaration of linux parallel dma operations **/
struct aml_dma_linux_par_ops {
struct aml_dma_linux_par_inner_ops {
void *(*do_thread)(void *data);
};
......@@ -69,7 +69,7 @@ struct aml_dma_linux_par_ops {
* Can be passed to generic aml_dma_*() functions.
**/
struct aml_dma_linux_par {
struct aml_dma_linux_par_ops ops;
struct aml_dma_linux_par_inner_ops ops;
struct aml_dma_linux_par_data data;
};
......@@ -80,8 +80,8 @@ struct aml_dma_linux_par {
* will be stored.
* @param nbreqs the initial number of slots for asynchronous requests that are
* in-flight (will be increased automatically if necessary).
* @param nbthreads the number of threads to launch for each request.
* @param op: default operator
* @param op_arg: default argument to the operator
* @return 0 if successful; an error code otherwise.
**/
int aml_dma_linux_par_create(struct aml_dma **dma, size_t nbreqs,
......
......@@ -61,7 +61,7 @@ struct aml_dma_linux_seq_data {
};
/** Declaration of available linux sequential dma operations **/
struct aml_dma_linux_seq_ops {
struct aml_dma_linux_seq_inner_ops {
/**
* Perform a sequential copy between source and destination
* pointers allocated with an aml_area_linux.
......@@ -77,7 +77,7 @@ struct aml_dma_linux_seq_ops {
* Can be passed to generic aml_dma_*() functions.
**/
struct aml_dma_linux_seq {
struct aml_dma_linux_seq_ops ops;
struct aml_dma_linux_seq_inner_ops ops;
struct aml_dma_linux_seq_data data;
};
......@@ -90,6 +90,7 @@ struct aml_dma_linux_seq {
* @param nbreqs the initial number of slots for asynchronous requests that are
* in-flight (will be increased automatically if necessary).
* @param op: default operator
* @param op_arg: default argument to the operator
*
* @return 0 if successful; an error code otherwise.
**/
......
......@@ -21,7 +21,9 @@
* on the virtual address space, and a pitch (distance between contiguous
* elements of the same dimension).
*
* @code
* #include <aml/layout/dense.h>
* @endcode
* @see aml_layout
* @{
**/
......@@ -58,17 +60,17 @@ struct aml_layout_dense {
/**
* Dense layout constructor.
* @param layout[out]: A pointer where to store a newly allocated layout.
* @param ptr[in]: The pointer to the data structure described by this layout.
* @param order[in]: The order in which dimensions are organized.
* @param[out] layout: A pointer where to store a newly allocated layout.
* @param[in] ptr: The pointer to the data structure described by this layout.
* @param[in] order: The order in which dimensions are organized.
* Can be AML_LAYOUT_ORDER_COLUMN_MAJOR or AML_LAYOUT_ORDER_ROW_MAJOR.
* @param element_size[in]: The size of each element in layout.
* @param ndims[in]: The number of dimensions of the layout.
* @param dims[in]: The number of elements along each dimension of the layout.
* @param stride[in]: The space between elements (in number of elements),
* @param[in] element_size: The size of each element in layout.
* @param[in] ndims: The number of dimensions of the layout.
* @param[in] dims: The number of elements along each dimension of the layout.
* @param[in] stride: The space between elements (in number of elements),
* along each dimension. If NULL then the stride is set to one for each
* dimension.
* @param pitch[in]: The space between consecutive elements of the same
* @param[in] pitch: The space between consecutive elements of the same
* dimension. If NULL, pitch is set to the number of elements in each dimension.
* @return -AML_ENOMEM if layout allocation failed.
* @return -AML_EINVAL if layout is NULL.
......@@ -86,7 +88,7 @@ int aml_layout_dense_create(struct aml_layout **layout,
/**
* Function to free a dense layout.
* @param layout[inout]: The layout to deallocate. NULL on return.
* @param[in,out] layout: The layout to deallocate. NULL on return.
**/
void aml_layout_dense_destroy(struct aml_layout **layout);
......@@ -236,4 +238,8 @@ extern struct aml_layout_ops aml_layout_column_ops;
**/
extern struct aml_layout_ops aml_layout_row_ops;
/**
* @}
**/
#endif
......@@ -15,7 +15,9 @@
* @defgroup aml_layout_native "AML Layout Internal API"
* @brief Layout API for internal management of layouts.
*
* @code
* #include <aml/layout/native.h>
* @endcode
* @{
**/
......@@ -24,8 +26,8 @@
* Layout assumes data is always stored in AML_LAYOUT_ORDER_FORTRAN order.
* Coordinates provided by the library will match the same order, i.e
* last dimension first.
* @param layout[in]: An initialized layout.
* @param coords[in]: The coordinates on which to access data.
* @param[in] layout: An initialized layout.
* @param[in] coords: The coordinates on which to access data.
* The first coordinate should be the last dimensions and so on to the last,
* coordinate, last dimension.
* @return A pointer to the dereferenced element on success.
......@@ -37,8 +39,8 @@ void *aml_layout_deref_native(const struct aml_layout *layout,
/**
* Return the layout dimensions in the order they are actually stored
* in the library.
* @param layout[in]: An initialized layout.
* @param dims[out]: The non-NULL array of dimensions to fill. It is
* @param[in] layout: An initialized layout.
* @param[in] dims: The non-NULL array of dimensions to fill. It is
* supposed to be large enough to contain ndims() elements.
* @return AML_SUCCESS on success, else an AML error code.
**/
......@@ -53,15 +55,15 @@ int aml_layout_dims_native(const struct aml_layout *layout,
* This function checks that the amount of elements along
* each dimensions of the slice actually fits in the original
* layout.
* @param layout[in]: An initialized layout.
* @param reshaped_layout[out]: a pointer where to store a
* @param[in] layout: An initialized layout.
* @param[out] reshaped_layout: a pointer where to store a
* newly allocated layout with the queried subset of the
* original layout on succes.
* @param offsets[in]: The index of the first element of the slice
* @param[in] offsets: The index of the first element of the slice
* in each dimension.
* @param dims[in]: The number of elements of the slice along each
* @param[in] dims: The number of elements of the slice along each
* dimension .
* @param strides[in]: The displacement (in number of elements) between
* @param[in] strides: The displacement (in number of elements) between
* elements of the slice.
* @return AML_SUCCESS on success, else an AML error code (<0).
**/
......@@ -70,4 +72,9 @@ int aml_layout_slice_native(const struct aml_layout *layout,
const size_t *offsets,
const size_t *dims,
const size_t *strides);
/**
* @}
**/
#endif
......@@ -18,7 +18,9 @@
* Padded layouts describe layouts that have been padded with neutral elements
* along one or several of their dimensions.
*
* @code
* #include <aml/layout/pad.h>
* @endcode
* @see aml_layout
* @{
**/
......@@ -61,4 +63,8 @@ extern struct aml_layout_ops aml_layout_pad_column_ops;
**/
extern struct aml_layout_ops aml_layout_pad_row_ops;
/**
* @}
**/
#endif
......@@ -18,7 +18,9 @@
* Layout for reshaping dense layouts when reshape method
* on dense layouts fails.
*
* @code
* #include <aml/layout/reshape.h>
* @endcode
* @see aml_layout
* @{
**/
......@@ -46,4 +48,8 @@ void aml_layout_reshape_destroy(struct aml_layout **l);
extern struct aml_layout_ops aml_layout_reshape_row_ops;
extern struct aml_layout_ops aml_layout_reshape_column_ops;
/**
* @}
**/
#endif
......@@ -65,7 +65,7 @@ struct aml_scratch_par_data {
};
/** The set of operation embeded in the parallel scratchpad **/
struct aml_scratch_par_ops {
struct aml_scratch_par_inner_ops {
/**
* Function to submit asynchronously scratchpad request.
* @param data: Argument of the thread starting the request,
......@@ -78,7 +78,7 @@ struct aml_scratch_par_ops {
/** Parallel implementation of a scratchpad **/
struct aml_scratch_par {
/** Set of operations embeded in the scratchpad **/
struct aml_scratch_par_ops ops;
struct aml_scratch_par_inner_ops ops;
/** Data embeded in the scratchpad **/
struct aml_scratch_par_data data;
};
......@@ -89,12 +89,10 @@ struct aml_scratch_par {
* @param scratch an address where the pointer to the newly allocated scratchpad
* structure will be stored.
*
* @param scratch_area the memory area where the scratchpad will be allocated.
* @param source_area the memory area containing the user data structure.
* @param dma the DMA that will be used for migrating data to and from
* the scratchpad.
* @param tiling the tiling to use on the user data structure and the scratch.
* @param nbtiles number of tiles to divide the scratchpad into.
* @param src_tiling the tiling to use on the source data structure
* @param scratch_tiling the tiling to use on the scratch
* @param nbreqs the initial number of slots for asynchronous request that
* are in-flight (will be increased automatically if necessary).
* @return 0 if successful; an error code otherwise.
......@@ -110,4 +108,8 @@ int aml_scratch_par_create(struct aml_scratch **scratch,
*/
void aml_scratch_par_destroy(struct aml_scratch **scratch);
/**
* @}
**/
#endif // AML_SCRATCH_PAR_H
......@@ -57,7 +57,7 @@ struct aml_scratch_seq_data {
};
/** The set of operation embeded in the sequential scratchpad **/
struct aml_scratch_seq_ops {
struct aml_scratch_seq_inner_ops {
/**
* Function to submit a scratchpad request.
* @param scratch: The scratchpad used for the request
......@@ -70,7 +70,7 @@ struct aml_scratch_seq_ops {
/** Sequential implementation of a scratchpad **/
struct aml_scratch_seq {
/** Set of operations embeded in the scratchpad **/
struct aml_scratch_seq_ops ops;
struct aml_scratch_seq_inner_ops ops;
/** Data embeded in the scratchpad **/
struct aml_scratch_seq_data data;
};
......
......@@ -15,7 +15,9 @@
* @defgroup aml_tiling_native "AML Tiling Internal API"
* @brief API for internal management of tilings.
*
* @code
* #include <aml/tiling/native.h>
* @endcode
* @{
**/
......
......@@ -12,7 +12,7 @@
#define AML_TILING_RESIZE_H 1
/**
* @defgroup aml_tiling_1d "AML Resizable Tiling"
* @defgroup aml_tiling_resize "AML Resizable Tiling"
* @brief tiling with not homogeneous tiles
*
* Implementation of a tiling for which the border tiles have the exact size of
......
......@@ -150,7 +150,7 @@ void aml_bitmap_copy_from_ulong(struct aml_bitmap *bitmap,
/**
* Copy a bitmap into an unsigned long array.
* @param bitmap: The bitmap to copy.
* @param src: An array of unsigned long storing bits to write.
* @param dst: An array of unsigned long storing bits to write.
* Bits are copied as is, i.e in the same order.
* @param size: The maximum number of bits in "src".
**/
......
......@@ -76,7 +76,7 @@ int aml_vector_getid(struct aml_vector *vector, void *elem);
int aml_vector_find(const struct aml_vector *vector, int key);
/**
* Resizes the vector. The keys of the newly allocated elements are set to the
* @param na value.
* na value.
* @param vector: an initialized vector structure.
* @param newsize: a new vector size. Only sizes greater than the current one
* will be honored; smaller sizes will result in a no-op.
......
......@@ -64,7 +64,7 @@ void *aml_dma_linux_par_do_thread(void *arg)
return NULL;
}
struct aml_dma_linux_par_ops aml_dma_linux_par_inner_ops = {
struct aml_dma_linux_par_inner_ops aml_dma_linux_par_inner_ops = {
aml_dma_linux_par_do_thread,
};
......
......@@ -63,7 +63,7 @@ int aml_dma_linux_seq_do_copy(struct aml_dma_linux_seq_data *dma,
return req->op(req->dest, req->src, req->op_arg);
}
struct aml_dma_linux_seq_ops aml_dma_linux_seq_inner_ops = {
struct aml_dma_linux_seq_inner_ops aml_dma_linux_seq_inner_ops = {
aml_dma_linux_seq_do_copy,
};
......
......@@ -62,7 +62,7 @@ void *aml_scratch_par_do_thread(void *arg)
return NULL;
}
struct aml_scratch_par_ops aml_scratch_par_inner_ops = {
struct aml_scratch_par_inner_ops aml_scratch_par_inner_ops = {
aml_scratch_par_do_thread,
};
......
......@@ -60,7 +60,7 @@ int aml_scratch_seq_doit(struct aml_scratch_seq_data *scratch,
req->dst, req->src);
}
struct aml_scratch_seq_ops aml_scratch_seq_inner_ops = {
struct aml_scratch_seq_inner_ops aml_scratch_seq_inner_ops = {
aml_scratch_seq_doit,
};
......
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