Manual merge from development branch.

.gitignore

@@ -17,15 +17,13 @@ CMakeSettings.json
 build*/
 cmake-build*/
 cppcheck/
-doc/html/
-doc/latex/
 src/Tools/version.cpp
 src/Tools/Documentation/strings.cpp
 test-regression-results/
 code_coverage_files/
 code_coverage_report/
-doc/doxygen/html/
-doc/doxygen/latex/
-doc/doxygen/xml/
+doc/build/
+doc/source/api/
+doc/output/
 
 __pycache__/

.gitlab-ci.yml

@@ -69,7 +69,7 @@ analysis-headers:
     - linux
   script:
     - ./scripts/generate_aff3ct_header.sh aff3ct.hpp
-    - diff aff3ct.hpp src/aff3ct.hpp
+    - diff aff3ct.hpp include/aff3ct.hpp
 
 analysis-git-submodules:
   stage: analysis
@@ -86,23 +86,25 @@ analysis-git-submodules:
     - source ./ci/tools/git-branch.sh
     - ./ci/analysis-git-submodule.sh
 
-documentation-sphinx:
+analysis-documentation:
   stage: analysis
   except:
     - schedules
   artifacts:
-    name: documentation-sphinx
+    name: analysis-documentation
     when: always
     paths:
-      - doc/sphinx/build/html
-      - doc/sphinx/build/latex
+      - doc/build/html
+      - doc/build/latex
+      - doc/build/doxygen
   tags:
-    - sphinx
+    - pip3
+    - doxygen
     - latex
+    - powerful
   script:
-    - cd doc/sphinx
-    - make html
-    - make latexpdf
+    - export THREADS="1"
+    - ./ci/analysis-documentation.sh
 
 build-linux-gcc-nointr:
   stage: build
@@ -136,7 +138,8 @@ build-linux-gcc-x64-sse4.2:
     GIT_SUBMODULE_STRATEGY: recursive
   except:
     - schedules
-  dependencies: []
+  dependencies:
+    - analysis-documentation
   tags:
     - linux
     - gcc
@@ -161,7 +164,8 @@ build-linux-gcc-x64-avx2:
   stage: build
   variables:
     GIT_SUBMODULE_STRATEGY: recursive
-  dependencies: []
+  dependencies:
+    - analysis-documentation
   tags:
     - linux
     - gcc
@@ -345,7 +349,8 @@ build-windows-gcc-x86-sse4.2:
     GIT_SUBMODULE_STRATEGY: recursive
   except:
     - schedules
-  dependencies: []
+  dependencies:
+    - analysis-documentation
   tags:
     - windows
     - gcc
@@ -370,7 +375,8 @@ build-windows-gcc-x64-avx2:
     GIT_SUBMODULE_STRATEGY: recursive
   except:
     - schedules
-  dependencies: []
+  dependencies:
+    - analysis-documentation
   tags:
     - windows
     - 64-bit
@@ -418,7 +424,8 @@ build-macos-clang-x64-sse4.2:
     GIT_SUBMODULE_STRATEGY: recursive
   except:
     - schedules
-  dependencies: []
+  dependencies:
+    - analysis-documentation
   tags:
     - macos
     - apple-clang
@@ -1305,7 +1312,7 @@ deploy-upload-ppa:
   except:
     - schedules
   dependencies:
-    - documentation-sphinx
+    - analysis-documentation
   allow_failure: true
   tags:
     - linux

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+  configuration: doc/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - epub
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: doc/requirements.txt
+
+# disable submodules
+submodules:
+  exclude: all
+  recursive: false

CMakeLists.txt

@@ -142,7 +142,7 @@ endif()
 
 # ------------------------------------------------------------------------------------------------------------- STRINGS
 if(NOT AFF3CT_EXT_STRINGS)
-    file(READ doc/sphinx/strings.rst AFF3CT_STRINGS)
+    file(READ doc/strings.rst AFF3CT_STRINGS)
 
     string(REPLACE "\\" "\\\\" AFF3CT_STRINGS "${AFF3CT_STRINGS}")
     string(REPLACE "\"" "\\\"" AFF3CT_STRINGS "${AFF3CT_STRINGS}")
@@ -367,7 +367,8 @@ macro(aff3ct_target_include_directories2 privacy dir)
 endmacro()
 
 # AFF3CT headers
-aff3ct_target_include_directories(PUBLIC "src" "aff3ct")
+aff3ct_target_include_directories(PRIVATE "src"     "aff3ct")
+aff3ct_target_include_directories(PUBLIC  "include" "aff3ct")
 
 # cli headers
 aff3ct_target_include_directories(PUBLIC "lib/cli/src" "cli")
@@ -576,15 +577,15 @@ if (AFF3CT_COMPILE_SHARED_LIB OR AFF3CT_COMPILE_STATIC_LIB)
             DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/aff3ct-${AFF3CT_VERSION_FULL}/"
             COMPONENT library)
 
-    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src/"
+    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/"
             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/aff3ct-${AFF3CT_VERSION_FULL}/aff3ct
             COMPONENT headers
             FILES_MATCHING PATTERN "*.h")
-    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src/"
+    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/"
             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/aff3ct-${AFF3CT_VERSION_FULL}/aff3ct
             COMPONENT headers
             FILES_MATCHING PATTERN "*.hpp")
-    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src/"
+    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/"
             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/aff3ct-${AFF3CT_VERSION_FULL}/aff3ct
             COMPONENT headers
             FILES_MATCHING PATTERN "*.hxx")
@@ -615,18 +616,18 @@ if (AFF3CT_COMPILE_SHARED_LIB OR AFF3CT_COMPILE_STATIC_LIB)
             FILES_MATCHING PATTERN "*.hxx")
 endif()
 
-if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/sphinx/build/latex/AFF3CT.pdf")
-    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/doc/sphinx/build/latex/AFF3CT.pdf"
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/build/latex/AFF3CT.pdf")
+    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/doc/build/latex/AFF3CT.pdf"
             DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/aff3ct-${AFF3CT_VERSION_FULL}/doc/pdf
             COMPONENT documentation)
 endif()
-if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/sphinx/build/html/")
-    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/doc/sphinx/build/html/"
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/build/html/")
+    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/doc/build/html/"
             DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/aff3ct-${AFF3CT_VERSION_FULL}/doc/html
             COMPONENT documentation)
 endif()
 if(AFF3CT_EXT_STRINGS)
-    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/doc/sphinx/strings.rst"
+    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/doc/strings.rst"
             DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/aff3ct-${AFF3CT_VERSION_FULL}/doc/strings
             COMPONENT documentation)
 endif()

ci/analysis-documentation.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -x
+
+if [ -z "$THREADS" ]
+then
+	echo "The 'THREADS' environment variable is not set, default value = 1."
+	THREADS=1
+fi
+
+cd doc/
+pip3 install --user -r requirements.txt
+rc=$?; if [[ $rc != 0 ]]; then exit $rc; fi
+
+export SPHINX_BUILDERNAME="latex"
+make clean
+sphinx-build -M latexpdf source build -j $THREADS
+rc=$?; if [[ $rc != 0 ]]; then exit $rc; fi
+
+export SPHINX_BUILDERNAME="html"
+sphinx-build -M html source build -j $THREADS
+rc=$?; if [[ $rc != 0 ]]; then exit $rc; fi

ci/check-documentation.py

@@ -137,8 +137,8 @@ def check_keys(keys_file, aff3ct_path, doc_path):
 			not_in_doc_keys.append(k)
 
 	# manages special key exceptions
-	exceptions_not_in_doc_keys = ["factory::Frozenbits_generator::parameters::p+pb-path"]
-	exceptions_doc_keys = ["factory::BFER::parameters::p+mpi-comm-freq", "factory::Launcher::parameters::except-a2l"]
+	exceptions_not_in_doc_keys = ["factory::Frozenbits_generator::p+pb-path"]
+	exceptions_doc_keys = ["factory::BFER::p+mpi-comm-freq", "factory::Launcher::except-a2l"]
 	for e in exceptions_not_in_doc_keys:
 		if e in not_in_doc_keys: not_in_doc_keys.remove(e)
 	for e in exceptions_doc_keys:
@@ -163,9 +163,9 @@ def check_keys(keys_file, aff3ct_path, doc_path):
 
 if __name__ == "__main__":
 	parser = argparse.ArgumentParser()
-	parser.add_argument('--keys',   action='store', dest='keys_file',   type=str, default='doc/sphinx/strings.rst')
+	parser.add_argument('--keys',   action='store', dest='keys_file',   type=str, default='doc/strings.rst')
 	parser.add_argument('--aff3ct', action='store', dest='aff3ct_path', type=str, default='build/bin/aff3ct')
-	parser.add_argument('--doc',    action='store', dest='doc_path',    type=str, default='doc/sphinx/source/user/simulation/parameters/')
+	parser.add_argument('--doc',    action='store', dest='doc_path',    type=str, default='doc/source/user/simulation/parameters/')
 
 	args = parser.parse_args()
 

ci/deploy-sonarqube-linux.sh

@@ -37,7 +37,7 @@ sed -i "s:{{ROOT_DIR}}:$PWD:g" $REPORTS_DIR/scan-build-*/*.plist
 
 # list of standard C++ includes in the system
 STD_CXX_INC=$(echo | gcc -xc++ -E -Wp,-v - 2>&1 | grep "^ " | sed -e :a -e '$!N; s/\n/,/; ta')
-PROJECT_CXX_INC="./src/, ./lib/date/include/date, ./lib/MIPP/src/, ./lib/MSVC/include/, ./lib/rang/include/, ./lib/cli/src/"
+PROJECT_CXX_INC="./src/, ./include/, ./lib/date/include/date, ./lib/MIPP/src/, ./lib/MSVC/include/, ./lib/rang/include/, ./lib/cli/src/"
 GCC_REGEX='(?<file>.*):(?<line>[0-9]+):[0-9]+:\\x20warning:\\x20(?<message>.*)\\x20\\[(?<id>.*)\\]'
 
 # Create the sonar config file on the fly

ci/deploy-upload-ppa.sh

@@ -9,7 +9,7 @@ fi
 
 cmake --version
 mkdir build
-mv doc/sphinx/build doc/sphinx/built
+mv doc/build doc/built
 cd build
 
 if [ -z "DISTRIBS" ]

ci/test-regression.py

@@ -29,7 +29,7 @@
 parser.add_argument('--binary-path',    action='store', dest='binaryPath',    type=str,   default="bin/aff3ct",              help='Path to the AFF3CT binary.')
 parser.add_argument('--start-id',       action='store', dest='startId',       type=int,   default=1,                         help='Starting id to avoid computing results one again.')                                       # choices=xrange(1,   +inf)
 parser.add_argument('--sensibility',    action='store', dest='sensibility',   type=float, default=1.0,                       help='Sensibility on the difference between new vs ref to verify a noise point.')               # choices=xrange(1.0, +inf)
-parser.add_argument('--n-threads',      action='store', dest='nThreads',      type=int,   default=0,                         help='Number of threads to use in the simulation (0 = all available).')                         # choices=xrange(0,   +ing)
+parser.add_argument('--n-threads',      action='store', dest='nThreads',      type=int,   default=0,                         help='Max number of threads to use in the simulation (0 = all available).')                     # choices=xrange(0,   +ing)
 parser.add_argument('--recursive-scan', action='store', dest='recursiveScan', type=bool,  default=True,                      help='If enabled, scan the path of refs recursively.')
 parser.add_argument('--max-fe',         action='store', dest='maxFE',         type=int,   default=100,                       help='Maximum number of frames errors to simulate per noise point.')                            # choices=xrange(0,   +inf)
 parser.add_argument('--min-fe',         action='store', dest='minFE',         type=int,   default=50,                        help='Minimum number of frames errors to take into account the simulated noise point.')         # choices=xrange(0,   +inf)
@@ -370,6 +370,17 @@ def passRate(self):
 	argsAFFECT = argsAFFECTcommand[:] # hard copy
 	argsAFFECT += simuRef.getSplitCommand()
 	argsAFFECT[len(argsAFFECTcommand)] = args.binaryPath;
+
+	# overrides nThreads if the ref specifies an inferior number
+	if "-t" in argsAFFECT and argsAFFECT.index("-t") +1 < len(argsAFFECT):
+		try:
+			refsNThreads = int(argsAFFECT[argsAFFECT.index("-t") + 1])
+		except (ValueError, TypeError):
+			refsNThreads = args.nThreads
+
+		if args.nThreads == 0 or refsNThreads < args.nThreads:
+			args.nThreads = refsNThreads
+
 	argsAFFECT += ["--ter-freq", "0", "-t", str(args.nThreads), "--sim-meta", simuRef.getMetadata("title")]
 	if args.maxFE:
 		argsAFFECT += ["-e", str(args.maxFE)]

cmake/Modules/UploadPPA.cmake

@@ -95,8 +95,8 @@ foreach(DISTRI ${AFF3CT_PPA_DISTRIB})
          "usr/include/aff3ct-${AFF3CT_VERSION_FULL}/*\n")
 
     file(WRITE "${DEBIAN_SOURCE_DIR}/debian/${CPACK_DEBIAN_PACKAGE_NAME}-doc.install"
-         "doc/sphinx/built/html/* usr/share/aff3ct-${AFF3CT_VERSION_FULL}/doc/html\n"
-         "doc/sphinx/built/latex/AFF3CT.pdf usr/share/aff3ct-${AFF3CT_VERSION_FULL}/doc/pdf/\n")
+         "doc/built/html/* usr/share/aff3ct-${AFF3CT_VERSION_FULL}/doc/html\n"
+         "doc/built/latex/AFF3CT.pdf usr/share/aff3ct-${AFF3CT_VERSION_FULL}/doc/pdf/\n")
 
     ##############################################################################
     # debian/copyright
@@ -131,7 +131,7 @@ foreach(DISTRI ${AFF3CT_PPA_DISTRIB})
 
     if(EXISTS ${CPACK_DEBIAN_RESOURCE_FILE_CHANGELOG})
         configure_file(${CPACK_DEBIAN_RESOURCE_FILE_CHANGELOG} ${DEBIAN_CHANGELOG} COPYONLY)
-      
+
         if(CPACK_DEBIAN_UPDATE_CHANGELOG)
             file(READ ${DEBIAN_CHANGELOG} DEBIAN_CHANGELOG_content)
             execute_process(COMMAND date -R

doc/sphinx/Makefile → doc/Makefile

@@ -11,7 +11,11 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+clean:
+	rm -rf build/doxygen/ source/api/
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/README.md

@@ -0,0 +1,27 @@
+# AFF3CT Documentation Generation
+
+**AFF3CT** uses [Sphinx](http://www.sphinx-doc.org) and [Doxygen](http://www.doxygen.nl/) to generate the documentation.
+
+Install Sphinx, Doxygen and Sphinx extensions:
+
+```bash
+sudo apt install python3 python3-pip librsvg2-bin doxygen
+pip3 install --user -r requirements.txt
+```
+
+Generate the HTML documentation:
+
+```bash
+make html
+```
+
+Generate the PDF documentation:
+
+```bash
+make latexpdf
+```
+
+**Be careful the previous `make` commands can take a long time (between 30 minutes and 1 hour).**
+
+The last command will create a new folder: `build/html`.
+In the `html` folder you just have to open the `index.html` file to read the generated documentation.