DOC: add sphinx documentation

doc/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file

doc/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

doc/source/api.rst

+.. _api:
+
+================
+Alignment module
+================
+
+.. automodule:: wlalign.alignment
+    :members: permutation_from_alignment, apply_alignment, length_wl_signature, signature_wl, wl_align
+
+=================
+Similarity module
+=================
+
+.. automodule:: wlalign.similarity
+    :members: graph_jaccard_index
+
+============
+Utils module
+============
+
+.. automodule:: wlalign.utils
+    :members: load_network, symmetrize_adj, check_is_adj, check_compatible_adj, check_is_alignment, check_can_write_file

doc/source/citation.rst

+.. _citation:
+
+====================
+How to cite WL-align
+====================
+If you use WL-align in your research, please cite the following article.
+
+    Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, Emanuele
+    Natale, Samuel Deslauriers-Gauthier; Network alignment and similarity
+    reveal atlas-based topological differences in structural connectomes.
+    Network Neuroscience 2021;
+    `DOI: 10.1162/netn_a_00199 <https://doi.org/10.1162/netn_a_00199>`_
+
+.. code:: bibtex
+
+    @article{wlalign,
+          author = {Frigo, Matteo and Cruciani, Emilio and Coudert, David and
+                    Deriche, Rachid and Natale, Emanuele and
+                    Deslauriers-Gauthier, Samuel},
+          title = {Network alignment and similarity
+                   reveal atlas-based topological differences in structural
+                   connectomes},
+          journal = {Network Neuroscience},
+          url = {https://hal.archives-ouvertes.fr/hal-03116143},
+          doi = {10.1162/netn_a_00199},
+          year = {2021}
+         }

doc/source/command-line-interface.rst

+.. _command-line-interface:
+
+===========================
+CLI: Command Line Interface
+===========================
+
+The user can align two graphs from the command line by providing their
+adjacency matrices in text form.
+The edge weights in each line must be separated by whitespaces.
+
+.. code:: bash
+
+    wlalign --help
+
+.. code:: text
+
+    usage: wlalign [-h] [--first_aligned FIRST_ALIGNED] [--k INT] [--l INT]
+                   [--force] [-v]
+                   in_graph1 in_graph2 out_matching
+
+    This program uses WL-align to compute an alignment between two graphs having
+    the same number of nodes. It takes as input their adjacency matrices and it
+    returns a matching (a.k.a. alignment) between their nodes.
+
+    positional arguments:
+      in_graph1             Path to the first graph to be aligned
+      in_graph2             Path to the second graph to be aligned
+      out_matching          Path where the matching will be saved. The first
+                            element of each row is the index of the node in the
+                            first graph that is aligned with the node in the
+                            second graph indexed by the second element of the row
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --first_aligned FIRST_ALIGNED
+                            The aligned version of the first input graph will be
+                            saved in the specified position (default: None)
+      --k INT               Width parameter (default: 2)
+      --l INT               Depth parameter (default: 2)
+      --force               Overwrite existing files (default: False)
+      -v, --verbose         Set verbose output (default: False)

doc/source/conf.py

+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import wlalign
+sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'WL-align'
+copyright = '2021, CoBCoM'
+author = 'Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, ' \
+         'Emanuele Natale, Samuel Deslauriers-Gauthier'
+
+# The short X.Y version
+version = wlalign.__version__
+# The full version, including alpha/beta/rc tags
+release = wlalign.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'nosidebar': True,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+html_static_path = []
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'wlaligndoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'wlalign.tex', 'WL-align Documentation',
+     'Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, ' \
+     'Emanuele Natale, Samuel Deslauriers-Gauthier', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'wlalign', 'wlalign Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'wlalign', 'WL-align Documentation',
+     author, 'wlalign', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+# Napoleon
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True

doc/source/contributors.rst

+.. _contributors:
+
+====================
+List of Contributors
+====================
+WL-align was conceived in the COATI and ATHENA Project Teams at Inria Sophia
+Antipolis - Méditerranée. The Python package was developed by:
+
+* `Matteo Frigo <https://www.mfrigo.com>`_ , ATHENA Project Team, Inria Sophia
+    Antipolis - Méditerranée.
+* `Emilio Cruciani <https://sites.google.com/view/emiliocruciani/>`_ , COATI
+    Project Team, Inria Sophia Antipolis - Méditerranée.

doc/source/funding.rst

+.. _funding:
+
+====================
+Funding
+====================
+The development of WL-align was funded by the European Research Council (ERC)
+under the European Union’s Horizon 2020 research and innovation program (ERC
+Advanced Grant agreement No 694665: `CoBCoM - Computational Brain Connectivity
+Mapping <https://project.inria.fr/cobcom/>`_ ).
+
+.. image:: img/logo_erc_eu.jpg
+    :align: center
+    :width: 600

doc/source/index.rst

+====================================
+Welcome to WL-align's documentation!
+====================================
+
+.. image:: https://gitlab.inria.fr/cobcom/wlalign/badges/master/pipeline.svg
+    :target: https://gitlab.inria.fr/cobcom/wlalign/-/commits/master"
+    :alt: Pipeline Status
+
+.. image:: https://gitlab.inria.fr/cobcom/wlalign/badges/master/coverage.svg
+    :target: https://gitlab.inria.fr/cobcom/wlalign/-/commits/master
+    :alt: Coverage Report
+
+
+`wlalign` is a pure Python package that implements the graph-alignment routine
+based on the generalization of the Weisfeiler-Lehman algorithm proposed in
+`this paper <https://doi.org/10.1162/netn_a_00199>`_.
+
+The software provides the ``wlalign`` Python module, which includes all the
+**functions and tools that are necessary for computing network alignments and
+similarity**.
+In particular, specific functions are devoted to:
+
+* Computing the **graph Jaccard index** of **similarity** between two weighted graphs.
+* Solving the **graph alignment problem** with **WL-align**.
+
+The package is `available at Pypi <#>`_ and can be easily installed from the
+command line.
+
+.. code:: bash
+
+    pip install wlalign
+
+
+Talon is a free software released under `MIT license <LICENSE>`_.
+
+Getting help
+============
+The preferred way to get assistance in running code that uses WL-align is
+through the issue system of the
+`Gitlab repository <https://gitlab.inria.fr/cobcom/wlalign>`_ where the
+source code is available.
+Developers and maintainers frequently check newly opened issues and will be
+happy to help you.
+
+
+Contributing guidelines
+=======================
+The development happens in the ``devel`` branch of the
+`Gitlab repository <https://gitlab.inria.fr/cobcom/wlalign>`_, while the
+``master`` is kept for the stable releases only.
+We will consider only merge requests towards the ``devel`` branch.
+
+
+How to cite
+===========
+If you publish works using WL-align, please cite us as indicated here:
+
+    Matteo Frigo, Emilio Cruciani, David Coudert, Rachid Deriche, Emanuele
+    Natale, Samuel Deslauriers-Gauthier; Network alignment and similarity
+    reveal atlas-based topological differences in structural connectomes.
+    Network Neuroscience 2021; doi: https://doi.org/10.1162/netn_a_00199
+
+In section :ref:`citation` you will find the Bibtex entry.
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Install
+
+    installation
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Command Line Interface
+
+    command-line-interface
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: API documentation
+
+    api
+
+.. toctree::
+    :maxdepth: 1
+    :caption: About the project
+
+    citation
+    contributors
+    license
+    funding

doc/source/installation.rst

+.. _installation:
+
+============
+Installation
+============
+WL-align runs only on Python 3.
+The installation has the following dependencies:
+
+* Numpy
+* Scipy
+
+If you are an Anaconda user, you may want to create a dedicated ``wlalign-env``
+environment and populate it with the right dependencies, then install WL-align.
+
+.. code:: bash
+
+    conda env create -n wlalign-env -f environment.yml
+    pip install wlalign
+
+Alternatively, you can install the dependencies and WL-align all via ``pip``.
+
+.. code:: bash
+
+    pip install numpy
+    pip install scipy
+
+    pip install wlalign
+
+To install WL-align directly from the source, clone this repository and run the
+standard local setup commands.
+
+.. code:: bash
+
+    git clone https://gitlab.inria.fr/cobcom/wlalign.git
+    cd wlalign
+    pip install -U .
+
+
+Check installation
+==================
+To check that WL-align has been properly installed, try to import the ``wlalign``
+module into a Python session and print the version as follows. If no error is
+raised, the installation has been successful.
+
+.. code:: python
+
+    >>> import wlalign
+    >>> print(wlalign.__version__)
+
+
+For developers
+==============
+If you are thinking about developing your own fork of WL-align, you may want to
+use the latest version in the ``devel`` branch of the repository and install it
+in editable mode.
+
+.. code:: bash
+
+    git clone https://gitlab.inria.fr/cobcom/wlalign.git
+    cd WL-align
+    git checkout devel
+    pip install -e .
+
+
+Tests
+~~~~~
+The package uses ``unittest`` as a testing suite.
+To run all the tests, execute the following command in the source's root
+directory.
+
+.. code:: bash
+
+    python -m unittest -v
+
+Test coverage can be checked with ``coverage`` as follows.
+
+.. code:: bash
+
+    coverage run -m unittest
+    coverage report -m
+
+
+Documentation
+~~~~~~~~~~~~~
+The sources of the documentation are in the ``doc`` folder.
+The compilation requires the ``sphinx`` package and the theme to be installed.
+
+.. code:: bash
+
+    pip install sphinx
+    pip install sphinx_rtd_theme
+
+To compile the documentation, move to the ``doc`` folder and run
+``make <format>``, where the format can be ``html``, ``latex`` or any other
+sphinx-compatible format.
+To get a local copy of the the html documentation, run the ``make html``
+command.
+
+.. code:: bash
+
+    cd doc
+    make clean  # deletes results of previous compilations
+    make html
+

doc/source/license.rst

+.. _license:
+
+====================
+License
+====================
+MIT License
+
+Copyright (c) 2021 WL-align developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.