Automatic examples documentation page generation

alpha_rips_persistence_bottleneck_distance example for python
Add intervals_in_dim function for simplex tree


git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/ST_cythonize@2055 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: 460fbe5db9f0c08776952106e729a21460bec36f

8 files changed, 94 insertions, 30 deletions

diff --git a/src/cython/doc/Makefile b/src/cython/doc/Makefile
index fc353a37..be3ff7c4 100644
--- a/src/cython/doc/Makefile
+++ b/src/cython/doc/Makefile
@@ -47,9 +47,13 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
+	rm -f examples.inc
 	rm -rf $(BUILDDIR)/*
 
+# GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean)
+
 html:
+	./generate_examples.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/src/cython/doc/bottleneck_distance_ref.rst b/src/cython/doc/bottleneck_distance_ref.rst
deleted file mode 100644
index 91a2ab05..00000000
--- a/src/cython/doc/bottleneck_distance_ref.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-===========================
-Bottleneck reference manual
-===========================
-
-.. autofunction:: gudhi.bottleneck_distance
diff --git a/src/cython/doc/bottleneck_distance_sum.rst b/src/cython/doc/bottleneck_distance_sum.rst
index 6fec9b7e..5c475d0d 100644
--- a/src/cython/doc/bottleneck_distance_sum.rst
+++ b/src/cython/doc/bottleneck_distance_sum.rst
@@ -11,5 +11,5 @@
 |      Bottleneck distance is the length of                       | distance at most b.                                                  |
 |      the longest edge                                           |                                                                      |
 +-----------------------------------------------------------------+----------------------------------------------------------------------+
-| :doc:`bottleneck_distance_user`                                 | :doc:`bottleneck_distance_ref`                                       |
+| :doc:`bottleneck_distance_user`                                 |                                                                      |
 +-----------------------------------------------------------------+----------------------------------------------------------------------+
diff --git a/src/cython/doc/examples.rst b/src/cython/doc/examples.rst
index 32b173c3..a89e0596 100644
--- a/src/cython/doc/examples.rst
+++ b/src/cython/doc/examples.rst
@@ -1,4 +1,4 @@
 Examples
 ########
 
-
+.. include:: examples.inc
diff --git a/src/cython/doc/generate_examples.py b/src/cython/doc/generate_examples.py
new file mode 100755
index 00000000..d64d506c
--- /dev/null
+++ b/src/cython/doc/generate_examples.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+
+from os import listdir
+
+"""This file is part of the Gudhi Library. The Gudhi library
+   (Geometric Understanding in Higher Dimensions) is a generic C++
+   library for computational topology.
+
+   Author(s):       Vincent Rouvreau
+
+   Copyright (C) 2017 INRIA
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+__author__ = "Vincent Rouvreau"
+__copyright__ = "Copyright (C) 2017 INRIA"
+__license__ = "GPL v3"
+
+"""
+generate_examples.py generates examples.inc to be included in examples.rst.
+Refer to Makefile and make.bat to see if it is correctly launched.
+"""
+
+output_file = open('examples.inc','w')
+
+output_file.write('.. only:: builder_html\n\n')
+
+for file in listdir('../example/'):
+    output_file.write("    * :download:`" + file + " <../example/" + file + ">`\n")
+
+output_file.close()
diff --git a/src/cython/doc/installation.rst b/src/cython/doc/installation.rst
index 4359c744..12d35821 100644
--- a/src/cython/doc/installation.rst
+++ b/src/cython/doc/installation.rst
@@ -42,7 +42,9 @@ Documentation
 =============
 
 To build the documentation, `sphinx-doc <http://http://www.sphinx-doc.org>`_ is
-required. Run the following commands in a terminal:
+required. Please refer to *conf.py* file to see which
+`sphinx-doc <http://http://www.sphinx-doc.org>`_ modules are required to
+generate the documentation. Run the following commands in a terminal:
 
 .. code-block:: bash
 
@@ -56,7 +58,7 @@ CGAL
 
 The :doc:`Alpha complex </alpha_complex_user>` data structure and
 :doc:`Tangential complex </tangential_complex_user>` data structures,
-:doc:`Bottleneck distance </bottleneck_distance_user>`requires CGAL, which is a
+:doc:`Bottleneck distance </bottleneck_distance_user>` requires CGAL, which is a
 C++ library which provides easy access to efficient and reliable geometric
 algorithms.
 
@@ -66,13 +68,17 @@ install this library according to your operating system is detailed
 
 The following examples require the Computational Geometry Algorithms Library:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* alpha_complex_from_points_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>`
 
 The following example requires CGAL version ≥ 4.8.0:
 
-* bottleneck_basic_example.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Eigen3
 ======
@@ -85,9 +91,11 @@ algorithms.
 
 The following examples require the `Eigen3 <http://eigen.tuxfamily.org/>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* alpha_complex_from_points_example.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Matplotlib
 ==========
@@ -99,12 +107,14 @@ formats and interactive environments across platforms.
 
 The following examples require the `Matplotlib <http://matplotlib.org>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* gudhi_graphical_tools_example.py
-* periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py
-* rips_complex_diagram_persistence_with_pandas_interface_example.py
-* rips_persistence_diagram.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_example.py>`
+    * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Numpy
 =====
@@ -115,9 +125,11 @@ scientific computing with Python.
 
 The following examples require the `NumPy <http://numpy.org>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* gudhi_graphical_tools_example.py
-* periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py
-* rips_complex_diagram_persistence_with_pandas_interface_example.py
-* rips_persistence_diagram.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_example.py>`
+    * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
diff --git a/src/cython/doc/make.bat b/src/cython/doc/make.bat
index 656c0105..ba009a90 100644
--- a/src/cython/doc/make.bat
+++ b/src/cython/doc/make.bat
@@ -41,6 +41,7 @@ if "%1" == "help" (
 )

 

 if "%1" == "clean" (

+	del examples.inc

 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i

 	del /q /s %BUILDDIR%\*

 	goto end

@@ -60,7 +61,10 @@ if errorlevel 9009 (
 	exit /b 1

 )

 

+:: GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean)

+

 if "%1" == "html" (

+	generate_examples.py

 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html

 	if errorlevel 1 exit /b 1

 	echo.

diff --git a/src/cython/doc/persistent_cohomology_user.rst b/src/cython/doc/persistent_cohomology_user.rst
index 1479fb1e..4ca4805d 100644
--- a/src/cython/doc/persistent_cohomology_user.rst
+++ b/src/cython/doc/persistent_cohomology_user.rst
@@ -97,7 +97,13 @@ Examples
 
 We provide several example files: run these examples with -h for details on their use.
 
-.. todo::
-    examples for persistence
+.. only:: builder_html
+
+    * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_example.py>`
+    * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
+    * :download:`random_cubical_complex_persistence_example.py <../example/random_cubical_complex_persistence_example.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 .. include:: biblio.rst