Fix Sphinx documentation errors and warnings (#265)

* Fix all sphinx warnings and errors. Removed repeat declarations of functions.

* Committing clang-format changes

* remove def of EXTENSION_MAPPING

* gitignore for docs and fix c structs

* Committing clang-format changes

---------

Co-authored-by: github-actions <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jean Luca Bez <[email protected]>

Author: 3 people

docs/.gitignore

@@ -0,0 +1,2 @@
+_build
+html

docs/source/Doxyfile.in

@@ -2237,7 +2237,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # C-preprocessor directives found in the sources and include files.
 # The default value is: YES.
 
-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES
 
 # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
 # in the source code. If set to NO, only conditional compilation will be
@@ -2246,7 +2246,7 @@ ENABLE_PREPROCESSING   = NO
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2287,7 +2287,9 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED            += ATTRIBUTE(x)=
+PREDEFINED            += __attribute__(x)=
+PREDEFINED            += __attribute__=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

docs/source/api.rst

@@ -11,6 +11,7 @@ The following macros are defined in the header file `src/commons/logging/include
 The available macros, which follow a similar usage to `printf`, are:
 
 .. code-block:: C
+
     LOG_ERROR
     LOG_WARNING
     LOG_INFO
@@ -20,6 +21,7 @@ The available macros, which follow a similar usage to `printf`, are:
 Each of these macros automatically prepends a timestamp and log level prefix to the output:
 
 .. code-block:: C
+
     [year-month-day hour:minute:second] [ERROR] 
     [year-month-day hour:minute:second] [WARNING] 
     [year-month-day hour:minute:second] [INFO] 
@@ -429,6 +431,7 @@ How to set up code formatter for PDC on Mac?
     3. Then follow instruction here to install clang-format: https://clang.llvm.org/get_started.html. I would suggest you do the following (suppose if you already have homebrew installed)
 
     .. code-block:: Bash
+
         cd $LLVM_SRC_ROOT
         mkdir build
         cd build
@@ -441,6 +444,7 @@ How to set up code formatter for PDC on Mac?
     4. To format all your source code, do the following
 
     .. code-block:: Bash
+
         cd pdc
         clang-format-v10 -i -style=file src/*
         find src -iname *.h -o -iname *.c | xargs clang-format-v10 -i -style=file
@@ -483,6 +487,7 @@ When calling your bridging functions, the best example you can follow is `src/te
 Remember, you must include all your bridging function calls inside the following code blocks, so that the process can have its own Julia runtime loaded. 
 
 .. code-block:: C
+
     jl_module_list_t modules = {.julia_modules = (char *[]){JULIA_HELPER_NAME}, .num_modules = 1};
     init_julia(&modules);
     ......
@@ -505,6 +510,7 @@ We provide docker support for PDC on such purpose.
 To build the docker image, you can run the following command in the root directory of PDC project:
 
 .. code-block:: Bash
+
     .docker/run_dev_base.sh
 
 This will mount your PDC project directory to `/workspaces/pdc` directory in the docker container and an initial step will be performed once you attach to the container. 
@@ -533,13 +539,15 @@ We currently only support to architectures, amd64 and arm64v8.
 To build the architecture-specific docker image on the machine with specific CPU architecture, you can run the following command in the root directory of PDC project:
 
 .. code-block:: Bash
+
     .docker/publish_dev_base.sh <docker_registry_namespace> <version>
 
 If you run the above command on an ARM64v8 CPU (say, Apple Silicon Mac), it will generate an image named '<docker_registry_namespace>/pdc_dev_base:<version>-arm64v8'. 
 If you run the above command on any Intel X64/AMD x64 CPU (say, Microsoft surface or Apple Intel Mac, or an Intel CPU VM from AWS/Azure/GCP/OCI), it will generate an image named '<docker_registry_namespace>/pdc_dev_base:<version>-amd64'.
 Once the above is done, you can pick the image build machine with fastest network and run the following
 
 .. code-block:: Bash
+
     .docker/publish_dev_base.sh <docker_registry_namespace> <version> 1
 
 This will create a multi-arch image with both amd64 and arm64v8 architectures in your registry under your namespace. 
@@ -565,11 +573,13 @@ Debugging PDC on Perlmutter with LinaroForge
 First, you need to start an interactive session on Perlmutter:
 
 .. code-block:: Bash
+
     salloc -N 1 -C cpu -q interactive -t 1:00:00
 
 Then, you can load the ``forge`` module:
 
 .. code-block:: Bash
+
     module load forge
     module list
 
@@ -582,19 +592,22 @@ Go to this website https://www.linaroforge.com/download-documentation and find t
 To run a test, let's lunch pdc_server with 4 cores:
 
 .. code-block:: Bash
+
     cd $PDC_HOME/build
     rm -rf ./pdc_tmp # optional if you need to clean up the PDC tmp directory
     srun -N 1 -n  4 -c 2 --mem=25600 --cpu_bind=cores ./bin/pdc_server.exe &
 
 To debug the client, you can run the following command:
 
 .. code-block:: Bash
+
     cd $PDC_HOME/build
     ddt --connect srun -N 1 -n  4 -c 2 --mem=25600 --cpu_bind=cores ./bin/pdc_client.exe
 
 But if you need to debug the server, you can prepend ``srun`` with ``ddt --connect``:
 
 .. code-block:: Bash
+
     cd $PDC_HOME/build
     rm -rf ./pdc_tmp # optional if you need to clean up the PDC tmp directory
     ddt --connect srun -N 1 -n  4 -c 2 --mem=25600 --cpu_bind=cores ./bin/pdc_server.exe &

docs/source/assumptions.rst

@@ -16,7 +16,6 @@ Usage:
 	./mpi_test.sh ./pdc_client_application MPIRUN_CMD number_of_servers number_of_clients arg1 arg2 ....
 	./run_multiple_test.sh ./pdc_client_application_1 ./pdc_client_application_2 ......
 
-
 ---------------------------
 PDC Hello World
 ---------------------------
@@ -42,7 +41,6 @@ PDC Hello World
 * The above command will start a server with 2 processes. Then it will start the application program with 4 processes. Finally, all servers are closed.
 * On supercomputers, "mpiexec" can be replaced with "srun", "jsrun" or "aprun".
 
-
 ---------------------------
 Simple I-O
 ---------------------------
@@ -58,7 +56,6 @@ Simple I-O
 	./run_test.sh ./obj_get_data
 	./mpi_test.sh ./obj_get_data mpiexec 2 4
 
-
 ---------------------------
 I-O with region mapping
 ---------------------------
@@ -76,7 +73,6 @@ I-O with region mapping
 	./run_test.sh ./region_obj_map_3D
 	./mpi_test.sh ./region_obj_map_3D mpiexec 2 4
 
-
 ---------------------------
 VPIC-IO and BD-CATS-IO
 ---------------------------
@@ -89,7 +85,6 @@ VPIC-IO and BD-CATS-IO
 
 	./run_multiple_test.sh ./vpicio ./bdcats
 
-
 * VPIC-IO:
 	* vpicio.c
 	* VPIC I/O is an example for writing multiple objects using PDC, where each object is a variable of particles.
@@ -108,15 +103,13 @@ VPIC-IO and BD-CATS-IO
 HACC-IO
 ---------------------------
 
-
 * The purpose of this benchmark is to evaluate the performance of the I/O system for the Hardware Accelerated Cosmology Code (HACC) simulation. The HACC framework uses N-body techniques to simulate the formation of structure in collisionless fluids under the influence of gravity in an expanding universe.
 * Each MPI rank writes 9 variables (with different data types) per particle for a total of 38 bytes.
 
 .. code-block:: Bash
 
 	./mpi_test.sh ./haccio mpiexec 1 num-procs num-particles
 	
-
 ---------------------------
 Tile-IO
 ---------------------------

docs/source/definitions.rst

@@ -19,26 +19,22 @@ Byna, Suren, Dong, Bin, Tang, Houjun, Koziol, Quincey, Mu, Jingqing, Soumagne, J
    :caption: Getting Started
 
    getting_started
-   .. definitions
-   .. assumptions
 
 .. toctree::
    :maxdepth: 2
    :caption: Overview
 
    introduction
    hdf5vol
-   .. performance
 
 .. toctree::
    :maxdepth: 2
    :caption: Resources
 
    hellopdcexample
+   examples
    api
    tools
-   .. inflightanalysis
-   .. futurework
 
 
 .. toctree::