Add a contributing guide + update other READMEs consequently.

Adding a summary in main README too.

Add a contributing guide + update other READMEs consequently.
77ba25ec · hhakim · 0bc49813 · 77ba25ec · 0bc49813 · 77ba25ec
Commit 77ba25ec authored 1 year ago by hhakim
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
+# How to contribute
+
+Below we describe the processes to follow for any contribution to the FAµST
+project.
+
+1. Posting issues on Gitlab
+========================
+
+Please specify these elements on any issue which might need it:
+
+- The system you're using (Linux, Mac OS X, Windows) for FAµST, its version.
+- The wrapper you're using (pyfaust and matfaust).
+- The installer you used (wheel package -- pip, conda, system packages -- .exe,
+  .rpm, .deb, .pkg).
+- The version of FAµST: check ``pyfaust.__version__`` on a Python terminal for
+  pyfaust or ``matfaust.version()`` on a Matlab terminal for matfaust.
+- 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
+====================
+
+Any contribution to the development is of course welcome. It might be a bug
+fix, a feature or an algorithm implementation.
+
+In order to contribute:
+
+- If you have an Inria account or are a member for the FAµST gitlab project
+  please fork the project (a button is provided on the gitlab frontpage of the
+  project). Then do a Merge Request. If you are member of the project you might
+  also directly push your branch (giving a meaningful name) and do your merge
+  request for this branch.
+
+- If you don't have have any account on Inria's gitlab you can clone the
+  project, do any modifications you want to do. Then send us the patch obtained
+  with the command ``git diff > my.patch``. Please send to all email addresses
+  listed in [contact section of the official web site](https://faust.inria.fr/contact/).
+
+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.
--- a/README.developer
+++ b/README.developer
-##########################################################################
########                 README for developer                  ##########
########                    FAuST Toolbox                       ##########
######## Flexible Approximate Multi-Layer Sparse Transform      ##########
##########################################################################


##########################################################################
General purpose:

The FAuST toolbox contains a C++ code implementing a general framework 
designed to factorize matrices of interest into multiple sparse factors. 
It contains a template CPU/GPU C++ code and a Matlab wrapper.
The algorithms implemented here are described in details in [1]- Le Magoarou
For more information on the FAuST Project, please visit the website of the 
project: <http://faust.inria.fr>

##########################################################################
Installation:

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


##########################################################################
FAuST structure directory: 

./CMake/ 
	--> contains ".cmake" files used to execute some internal cmake 
		command as to find the path of the externals library, Matlab Path, 
		Python Path, ...
./gen_doc/
	--> contains both user and developer documentation: 
			- Developer documentation with Doxygen tool
			- User tutorials: jupyter notebooks and matlab live scripts
./misc/
	--> contains the tests (Ctest tool), the demonstrations, the data (or a script to download them), 
		the configuration files, and Continuous 
		Integration job scripts (used in .gitlab-ci.yml)
./src/
	--> contains the C++ sources of the project
./wrapper/
	--> contains the wrapper of the project (Matlab, Python)
##########################################################################

##########################################################################
Documentation for developer: Doxygen  

The Doxygen documentation is available in the following directory: 
./gen_doc/ 
To build Doxygen documentation, build the project with following option: 
cmake .. -DBUILD_DOCUMENTATION="ON"
The configuration of Doxygen are defined in the file ./gen_doc/Doxyfile.in
Main page of doxygen is available in following link :
./build/doc/html/index.html

Specific wrapper API documentation has been added and is also generated through doxygen
when wrapper building cmake variables are set. And more precisely the C++ doxydoc can be excluded if the 
cmake variable EXCLUDE_FAUST_LIB_INSTALL is set (this feature is used for release packages).
The documentation is automatically uploaded to gitlab each time a (release) tag is added to the gitlab project.
##########################################################################


##########################################################################
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 
public link: 
https://cdash-ci.inria.fr/CDash/index.php?project=faust
CDash is not so used anymore, the test reports are directly uploaded on gitlab (cf. README-tests-ci-release.md)

For more details concerning CI (Virtual Machines, etc.), refer to ci.inria.fr and cloud stack.
https://ci.inria.fr project faust2
##########################################################################

##########################################################################
References:

[1]	Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse 
	approximations of matrices and applications", Journal of Selected 
	Topics in Signal Processing, 2016.
	<https://hal.archives-ouvertes.fr/hal-01167948v1>
##########################################################################	
\ No newline at end of file
--- 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
+============================
+
+The FAuST toolbox contains a C++ code implementing a general framework
+designed to factorize matrices of interest into multiple sparse factors.
+It contains a template CPU/GPU C++ code and a Matlab wrapper.
+The algorithms implemented here are described in details in [1]- Le Magoarou
+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
+===============
+
+[https://faust.inria.fr](https://faust.inria.fr) (for pre-built packages) and README.md (for building)
+
+<a name="struct"/>
+3. FAuST structure directory
+============================
+
+- ``./CMake/``
+	 contains ".cmake" files used to execute some internal cmake
+	command as to find the path of the externals library, Matlab Path,
+	Python Path, ...
+- ``.gen_doc/``
+     contains both user and developer documentation:
+		- Developer documentation with Doxygen tool
+		- User tutorials: jupyter notebooks and matlab live scripts
+- ``.gpu_mod``
+     git submodule for GPU implementations.
+
+- ``.misc/``
+     contains the tests (Ctest tool), the demonstrations, the data (or a script to download them),
+	the configuration files, and Continuous
+	Integration job scripts (used in .gitlab-ci.yml)
+- ``.src/``
+     contains the C++ sources of the project
+- ``/wrapper/``
+     contains the wrapper of the project (Matlab, Python)
+
+
+
+<a name="api_doc"/>
+4. API Documentation: Doxygen
+==========================
+
+The Doxygen documentation is available in the following directory:
+``./gen_doc/``
+To build Doxygen documentation, build the project with following option:
+``cmake .. -DBUILD_DOCUMENTATION="ON"``
+The configuration of Doxygen are defined in the file ``./gen_doc/Doxyfile.in``
+Main page of doxygen is available in following link :
+``./build/doc/html/index.html``
+
+Specific wrapper API documentation has been added and is also generated through doxygen
+when wrapper building cmake variables are set. And more precisely the C++ doxydoc can be excluded if the
+cmake variable ``EXCLUDE_FAUST_LIB_INSTALL`` is set (this feature is used for release packages).
+The documentation is automatically uploaded to gitlab each time a (release) tag is added to the gitlab project.
+
+The online Doxygen doc is available
+[here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/index.html).
+
+
+
+<a name="ci"/>
+5. 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
+public link:
+[CDash FAµST project](https://cdash-ci.inria.fr/index.php?project=faust)
+CDash is not so used anymore, the test reports are directly uploaded on gitlab (cf. README-tests-ci-release.md)
+
+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
+========================
+
+Please consult the guide [here](CONTRIBUTING.md)
+
+<a name="refs"/>
+7. References
+=============
+
+[1]	Le Magoarou L. and Gribonval R., "Flexible multi-layer sparse
+	approximations of matrices and applications", Journal of Selected
+Topics in Signal Processing, 2016.
+<https://hal.archives-ouvertes.fr/hal-01167948v1>
+
+
--- a/README.md
+++ b/README.md
@@ -4,8 +4,20 @@
 # FAuST Toolbox -- Flexible Approximate Multi-Layer Sparse Transform


-General purpose
-===============
+### 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)
+
+
+<a name="gen_intro"/>
+1. General purpose
+==================

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

 ---

-Dependencies
-============
+<a name="deps"/>
+2. 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.
 The ``gpu_mod`` submodule must be checked out in order to enable this function.
@@ -37,7 +51,8 @@ the CMake script indicate if the match is not appropriate).

 ---

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

 	Unpack the directory.
@@ -56,8 +71,9 @@ 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).

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

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

@@ -72,8 +88,9 @@ Quick Build of the python wrappers (pyfaust) on UNIX (without MATLAB and MATIO)
 ---


-Using Docker for a quick build of the python wrappers (pyfaust) on Linux without any dependency burden
-==================================================================================================
+<a name="docker_quick_build_pyfaust"/>
+5. 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:
@@ -106,6 +123,7 @@ 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)
 ============================================

@@ -122,8 +140,16 @@ Pre-compiled packages from Gitlab Continuous Integration are also available. Exc
 - [Linux (.rpm, .deb) packages](https://gitlab.inria.fr/faustgrp/faust/-/jobs/artifacts/master/download?job=package_linux_release)  
 - [Linux (.rpm, .deb) packages with embedded static matio library](https://gitlab.inria.fr/faustgrp/faust/-/jobs/artifacts/master/download?job=package_linux_release)  
 - 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
+========================
+
+Please consult the guide [here](CONTRIBUTING.md) and the [README for developers](README.developer.md).
 ---
+<a name="refs"/>
+
 License
 ========