Minor fixes in READMEs titles + automatic TOCs.

0e539cee · hhakim · 91e0e7cc · 0e539cee · 0e539cee · 0e539cee
Commit 0e539cee authored 1 year ago by hhakim
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
 # How to contribute

+[[_TOC_]]
+
 Below we describe the processes to follow for any contribution to the FAµST
 project.

-1. Posting issues on Gitlab
-========================
+### Posting issues on Gitlab

 Please specify these elements on any issue which might need it:

@@ -17,8 +18,7 @@ Please specify these elements on any issue which might need it:
 - Explain clearly the problem you ran into or the feature you're intersting in
  and preferably give a snippet of code to reproduce easily.

-2. Code contribution
-====================
+### Code contribution

 Any contribution to the development is of course welcome. It might be a bug
 fix, a feature or an algorithm implementation.
@@ -40,5 +40,5 @@ Before sending us your patches or merge requests, please ensure as much as
 possible that the project is still able to build and that related tests pass
 (but we'll help you in that process if you find it too complicated).
 For any further information about building please consult the main
-(README)[README.md] (an easy Docker way is provided to build pyfaust wrappers)
-and (README-tests-ci-release.md) about tests.
+[README](README.md) (an easy Docker way is provided to build pyfaust wrappers)
+and [tests README](README-tests-ci-release.md).
--- a/README-tests-ci-release.md
+++ b/README-tests-ci-release.md
@@ -5,23 +5,10 @@ and maintenance related elements for the FAµST project.
 There are specific tests for each package/language used in the project. You'll
 find a section for each one of them in the next of this document.

-### Summary
-1. [Test policy on Gitlab](#gitlab_pol_test)  
-2. [Testing pyfaust/matfaust](#py_matfaust_tests)  
-2.1 [Test scripts for pyfaust/matfaust](#py_matfaust_tests)  
-2.2 [Gitlab continuous integration (ci) job](#py_mat_test_ci_jobs)  
-2.3 [Test report on Gitlab pages](#py_mat_test_reports)  
-2.4 [Doctest](#doctest)  
-2.5 [Test coverage](#test_cover)
-3. [FAµST C++ core tests](#cpp_tests)  
-3.1 [Tests](#cpp_tests)  
-3.2 [Gitlab continuous integration (ci) job](#py_mat_test_ci_jobs)  
-3.3 [Test report on Gitlab pages](#cpp_test_report)
-4. [Package tests and automatic release](#test_release_packages)  
-
-<a name="gitlab_pol_test"/>
-
-**1. Test policy on Gitlab**
+[[_TOC_]]
+
+
+### Test policy on Gitlab

 A strongly strict policy is applied on Gitlab test jobs.
 The goal is to ensure the non-regression of the project (which has a large base of
@@ -38,12 +25,10 @@ they won't/shouldn't reach the release stage.
 results and push a git-tag to release new packages but in that case at least
 the packages tests must pass or it will fail).

-**2. Testing pyfaust/matfaust**  
+### Testing pyfaust/matfaust


-**<a name="py_matfaust_tests">
-2.1 Test scripts for pyfaust/matfaust
-</a>**
+#### Test scripts for pyfaust/matfaust

 - Directory location: ``misc/test/src/Python`` for pyfaust and
  ``misc/test/src/Matlab``
@@ -60,9 +45,7 @@ recent FAµST API is needed).
      ``pyfaust.Faust`` class and all algorithms/functions),
    * ``FaustTest.m`` (31 unit tests for the ``matfaust.Faust`` class), ``FaustFactoryTest.m`` (39 unit tests for factorizations and other algorithms).

-**<a name="py_mat_test_ci_jobs">
-2.2 Gitlab continuous integration (ci) job
-</a>**
+#### Gitlab continuous integration (ci) job

 - All ci jobs are defined in the ``.gitlab-ci.yml`` file.
 - Gitlab ci jobs: ``ctest_python`` for pyfaust, ``ctest_matlab`` for matfaust.
@@ -72,9 +55,7 @@ recent FAµST API is needed).
  executes (on a Linux/MacOS VM) the test and unit tests above and other test scripts.
  The configuration of ctest for running the tests is located in ``misc/test/CMakeLists.txt``

-**<a name="py_mat_test_reports">
-2.3 Test reports on Gitlab pages
-</a>**
+#### Test reports on Gitlab pages

 - On the end of ``ctest_python``/``ctest_matlab`` execution a test report in HTML
  is automatically uploaded to the project Gitlab pages (as a hidden page).
@@ -84,9 +65,7 @@ recent FAµST API is needed).
  (if this link doesn't work, the associated pipeline has been deleted on Gitlab,
  please look [here](https://gitlab.inria.fr/faustgrp/faust/-/jobs) for a recent ``ctest_python``/``ctest_matlab`` output).

-**<a name="doctest">
-2.4 Doctest
-</a>**
+#### Doctest

 The pyfaust/matfaust API comes with many examples integrated on the [documentation](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/index.html).
 They are all fully tested in the
@@ -97,9 +76,7 @@ to run every night.
 If any of the tested pyfaust/matfaust submodules or functions fails (and they are all tested at the time of
 writing), the erroneous tests will be displayed in the ci job output.

-**<a name="test_cover">
-2.5 Test Coverage
-</a>**
+#### Test Coverage

 It really matters to keep a metric of how much code is covered by the tests in the project.

@@ -122,16 +99,14 @@ to pursue for a larger coverage.
 - About GPU code: unfortunately no automatic testing is made for GPU code
  because no NVIDIA GPU is available on VMs/Docker daemons that run the project gitlab-runners.

-**<a name="cpp_tests">
-3. FAµST C++ core tests
-</a>**
+### FAµST C++ core tests

-#### 3.1 Tests
+#### Tests

 - Directory location: ``misc/test/src/C++`` and ``misc/test/src/C++/unit``

-#### 3.2 Gitlab continuous integration (ci) jobs
-<a name="cpp_test_ci_jobs"/>
+#### Gitlab continuous integration (ci) jobs
+

 - Gitlab ci job: ``ctest`` performs C++ tests.
 -  Note that for a matter of pipeline speed this ci job runs only if there are changes in ``src/**/*``or ``misc/test/src/C++/**/*``.
@@ -140,8 +115,8 @@ For the same reason another ci job named ``ctest_nightly`` is made to run the te
 ``ctest_nightly_win10``), for the moment the macos' is disabled mainly because the macos' runs in monothread (see ``.gitlab-ci.yml``).
 - For more details about ctest, take a look at [2.2](#py_mat_test_ci_jobs).

-#### 3.3 Test report on Gitlab pages
-<a name="cpp_test_report"/>
+#### Test report on Gitlab pages
+

 - On the end of ``ctest`` ci job execution a test report in HTML
  is automatically uploaded to the project Gitlab pages (as a hidden page).
@@ -153,8 +128,6 @@ For the same reason another ci job named ``ctest_nightly`` is made to run the te

 - At the time of writing it exist 167 C++ tests ran by the ctest ci job. It includes many unit tests and all these tests passed the latest pipeline.

-**<a name="test_release_packages">
-4. Package tests and automatic release
-</a>**
+### Package tests and automatic release

 TODO
--- a/README.developer.md
+++ b/README.developer.md
 # Readme for developers


-### Summary
-1. [General purpose and features](#gen_intro)  
-2. [Installation](#install)  
-3. [Project structure](#struct)
-4. [API Documentation: Doxygen](#api_doc)
-5. [Continuous Integration](#ci)
-6. [Contributing to FAµST](#contributing)
-7. [References](#refs)
-
-<a name="gen_intro"/>
-1. General purpose and features
-============================
+[[_TOC_]]
+
+### General purpose and features

 The FAuST toolbox contains a C++ code implementing a general framework
 designed to factorize matrices of interest into multiple sparse factors.
@@ -22,15 +13,12 @@ For more information on the FAuST Project, please visit the website of the
 project: [https://faust.inria.fr](https://faust.inria.fr)


-<a name="install"/>
-2. Installation
-===============
+### Installation

 [https://faust.inria.fr](https://faust.inria.fr) (for pre-built packages) and README.md (for building)

-<a name="struct"/>
-3. FAuST structure directory
-============================
+
+### FAuST structure directory

 - ``./CMake/``
 	 contains ".cmake" files used to execute some internal cmake
@@ -54,9 +42,8 @@ project: [https://faust.inria.fr](https://faust.inria.fr)



-<a name="api_doc"/>
-4. API Documentation: Doxygen
-==========================
+
+### API Documentation: Doxygen

 The Doxygen documentation is available in the following directory:
 ``./gen_doc/``
@@ -76,9 +63,8 @@ The online Doxygen doc is available



-<a name="ci"/>
-5. Continuous Integration
-=========================
+
+### Continuous Integration

 The Continuous Integration for the project FAUST is based on the CDash tool
 (see. http://www.cdash.org/). The building and test are available on the
@@ -89,15 +75,13 @@ CDash is not so used anymore, the test reports are directly uploaded on gitlab (
 For more details concerning CI (Virtual Machines, etc.), refer to ci.inria.fr and cloud stack.
 https://ci.inria.fr project faust2

-<a name="contributing"/>
-6. Contributing to FAµST
-========================
+
+### Contributing to FAµST

 Please consult the guide [here](CONTRIBUTING.md)

-<a name="refs"/>
-7. References
-=============
+
+### References

 [1]	Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse
 	approximations of matrices and applications", Journal of Selected

--- a/README.md
+++ b/README.md
+![FAµST Logo](./gen_doc/images/logo.png)  
 [![pipeline status](https://gitlab.inria.fr/faustgrp/faust/badges/hakim_branch/pipeline.svg)](https://gitlab.inria.fr/faustgrp/faust/commits/hakim_branch)
 ![pyfaust test coverage](https://gitlab.inria.fr/faustgrp/faust/badges/hakim_branch/coverage.svg?job=pyfaust_test_code_coverage&key_text=pyfaustcov)
 ![matfaust test coverage](https://gitlab.inria.fr/faustgrp/faust/badges/hakim_branch/coverage.svg?job=matfaust_test_code_coverage&key_text=matfaustcov)
-![FAµST Logo](./gen_doc/images/logo.png)

 # FAuST Toolbox -- Flexible Approximate Multi-Layer Sparse Transform


-### Summary
-1. [General purpose and features](#gen_intro)  
-2. [Dependencies](#deps)  
-3. [Build on UNIX](#build_unix)
-4. [Quick Build of pyfaust](#quick_build_pyfaust)
-5. [Using Docker for a quick build pyfaust](#docker_quick_build_pyfaust)
-6. [Quickest install without building](#prebuilt_pkgs)
-7. [Contributing to FAµST](#contributing)
-8. [Credits -- Contacts -- References](#refs)
+[[_TOC_]]


-<a name="gen_intro"/>
-1. General purpose
-==================
+### General purpose

 The FAuST toolbox contains a C++ code implementing a general framework
 designed to factorize matrices of interest into multiple sparse factors.
@@ -32,9 +22,8 @@ project: [FAµST website](http://faust.inria.fr)

 ---

-<a name="deps"/>
-2. Dependencies
-===============
+
+### Dependencies

 - cuda (preferably cuda 12 latest version but 9 and 11 are also supported).
 There is a known bug on cuda 11.4 (issue #305). CUDA is optional, only used if cmake option ``USE_GPU_MOD`` is ON.
@@ -53,9 +42,8 @@ the CMake script indicate if the match is not appropriate).

 ---

-<a name="build_unix"/>
-3. Build on UNIX
-=====================
+
+### Build on UNIX

 	Unpack the directory.
 	mkdir ./build
@@ -73,9 +61,8 @@ For more information, please refer to the [Mathworks website](http://fr.mathwork
 Many CMake build options are available (cf. [CMakeLists.txt](./CMakeLists.txt)). It might be quite complicated to deal with them at start (refer to gitlab ci building scripts in [./misc/continuous\_integration/jobs/](./misc/continuous_integration/jobs/) or the [.gitlab-ci.yml](.gitlab-ci.yml) root script to get some insight).

 ---
-<a name="quick_build_pyfaust"/>
-4. Quick Build of the python wrappers (pyfaust) on UNIX (without MATLAB and MATIO)
-==================================================================================
+
+### Quick Build of the python wrappers (pyfaust) on UNIX (without MATLAB and MATIO)

 (With Eigen, Python3 with Cython, numpy and scipy installed)

@@ -90,9 +77,8 @@ Many CMake build options are available (cf. [CMakeLists.txt](./CMakeLists.txt)).
 ---


-<a name="docker_quick_build_pyfaust"/>
-5. Using Docker for a quick build of the python wrappers (pyfaust) on Linux without any dependency burden
-=========================================================================================================
+
+### Using Docker for a quick build of the python wrappers (pyfaust) on Linux without any dependency burden

 First you need to install [docker](https://docs.docker.com/engine/install/) or ``podman-docker``.
 Then follow the next commands:
@@ -125,9 +111,8 @@ Thanks to the docker directory mapping you can do it outside of the docker conta

 ---

-<a name="prebuilt_pkgs"/>
-Quickest Install on Linux, Windows and macOS (pre-built pakages)
-============================================
+
+### Quickest Install on Linux, Windows and macOS (pre-built pakages)

 Please refer to the document [Installation guides](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/md_README.html)
 to install the FAUST toolbox.
@@ -144,30 +129,30 @@ Pre-compiled packages from Gitlab Continuous Integration are also available. Exc
 - Python PIP (pre-compiled) packages: for [Linux](https://gitlab.inria.fr/faustgrp/faust/-/jobs/artifacts/master/download?job=package_linux_purepy_release), [macOS](https://gitlab.inria.fr/faustgrp/faust/-/jobs/artifacts/master/download?job=package_macos_purepy_release) and [Windows 10](https://gitlab.inria.fr/faustgrp/faust/-/jobs/artifacts/master/download?job=package_win_purepy_release). Or preferably, refer to [pypi pyfaust](https://pypi.org/project/pyfaust) or [anaconda pyfaust](https://anaconda.org/pyfaust/pyfaust).
 ---

-<a name="contributing"/>
-7. Contributing to FAµST
-========================
+
+### Contributing to FAµST

 Please consult the guide [here](CONTRIBUTING.md) and the [README for developers](README.developer.md).
+
 ---
-<a name="refs"/>

-License
-========
+
+### License -- Credits -- Contacts -- References
+
+#### License

 Cf. license.txt

 ---

-Contacts
-========
+#### Contacts

 	Rémi Gribonval: remi.gribonval@inria.fr
 	Hakim: hakim.hadj-djilani@inria.fr
+    Pascal Carrivain: pascal.carrivain@inria.fr


-Credits
-========
+#### Credits

 Researchers:
 Luc Le Magoarou
@@ -179,8 +164,7 @@ Adrien Leman (2016), Nicolas Bellot(2015-2016), Thomas Gautrais (2015), Hakim Ha

 ---

-References
-==========
+#### References

 [1]	[Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse
 	approximations of matrices and applications", Journal of Selected