From 9df2c0460d5ca9b646fa228fb3b228aeed8d967a Mon Sep 17 00:00:00 2001 From: Vincent Rouvreau Date: Thu, 26 Sep 2024 16:47:29 +0200 Subject: [PATCH 1/4] try sphinx_autodoc_typehints --- src/python/doc/conf.py | 5 ++- src/python/gudhi/sklearn/rips_persistence.py | 42 ++++++++++---------- 2 files changed, 25 insertions(+), 22 deletions(-) diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py index 76c8e15ece..6adf827328 100755 --- a/src/python/doc/conf.py +++ b/src/python/doc/conf.py @@ -8,18 +8,21 @@ sys.path.insert(0, os.path.abspath(".")) extensions = [ + "sphinx.ext.napoleon", + # let napoleon be the first extension, cf. https://github.com/tox-dev/sphinx-autodoc-typehints/issues/15 "matplotlib.sphinxext.plot_directive", "sphinx.ext.autodoc", + "sphinx_autodoc_typehints", "sphinx.ext.doctest", "sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ext.viewcode", - "sphinx.ext.napoleon", "sphinxcontrib.bibtex", "sphinx_paramlinks", ] autodoc_class_signature = "separated" +autodoc_typehints = "description" bibtex_bibfiles = ["../../biblio/bibliography.bib"] diff --git a/src/python/gudhi/sklearn/rips_persistence.py b/src/python/gudhi/sklearn/rips_persistence.py index 68f0646e14..b5c643fb1f 100644 --- a/src/python/gudhi/sklearn/rips_persistence.py +++ b/src/python/gudhi/sklearn/rips_persistence.py @@ -52,25 +52,25 @@ def __init__( homology_coeff_field: int = 11, n_jobs: Optional[int] = None, ): - """ - Constructor for the RipsPersistence class. - - Parameters: - homology_dimensions (int or list of int): The returned persistence diagrams dimension(s). - Short circuit the use of :class:`~gudhi.representations.preprocessing.DimensionSelector` when only one - dimension matters (in other words, when `homology_dimensions` is an int). - threshold (float): Rips maximal edge length value. Default is +Inf. Ignored if input_type is 'distance coo_matrix'. - input_type (str): Can be 'point cloud' when inputs are point clouds, 'full distance matrix', - 'lower distance matrix' when inputs are lower triangular distance matrix (can be full square, - but the upper part will not be considered), or 'distance coo_matrix' for a distance matrix in SciPy's - sparse format, which should contain each edge at most once (avoid the symmetric) and no diagonal entry. - Default is 'point cloud'. - num_collapses (int|str): Specify the number of iterations of :func:`~gudhi.flag_filtration.edge_collapse.reduce_graph` - (edge collapse) to perform on the graph. Default value is 'auto'. - homology_coeff_field (int): The homology coefficient field. Must be a prime number. Default value is 11. - n_jobs (Optional[int]): Number of jobs to run in parallel. `None` (default value) means `n_jobs = 1` unless in a - joblib.parallel_backend context. `-1` means using all processors. cf. - https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for more details. + """Constructor for the RipsPersistence class. + + :param homology_dimensions: The returned persistence diagrams dimension(s). + Short circuit the use of :class:`~gudhi.representations.preprocessing.DimensionSelector` when only one + dimension matters (in other words, when `homology_dimensions` is an int). + :param threshold: Rips maximal edge length value. Default is +Inf. Ignored if input_type is + 'distance coo_matrix'. + :param input_type: Can be 'point cloud' when inputs are point clouds, 'full distance matrix', + 'lower distance matrix' when inputs are lower triangular distance matrix (can be full square, + but the upper part will not be considered), or 'distance coo_matrix' for a distance matrix in SciPy's + sparse format, which should contain each edge at most once (avoid the symmetric) and no diagonal entry. + Default is 'point cloud'. + :param num_collapses: Specify the number of iterations of + :func:`~gudhi.flag_filtration.edge_collapse.reduce_graph` (edge collapse) to perform on the graph. + Default value is 'auto'. + :param homology_coeff_field: The homology coefficient field. Must be a prime number. Default value is 11. + :param n_jobs: Number of jobs to run in parallel. `None` (default value) means `n_jobs = 1` unless in a + joblib.parallel_backend context. `-1` means using all processors. cf. + https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for more details. """ self.homology_dimensions = homology_dimensions self.threshold = threshold @@ -165,7 +165,7 @@ def __transform(self, inp): dgm = _sparse(inp.row, inp.col, inp.data, inp.shape[0], max_dimension=max_dimension, max_edge_length=threshold, homology_coeff_field=self.homology_coeff_field) else: raise ValueError("Only 'point cloud', 'lower distance matrix', 'full distance matrix' and 'distance coo_matrix' are valid input_type") # move to __init__? - + # dgm stops at n-2 return [dgm[dim] if dim < len(dgm) else np.empty((0,2)) for dim in self.dim_list_] @@ -177,7 +177,7 @@ def transform(self, X, Y=None): :return: Persistence diagrams in the format: - - If `homology_dimensions` was set to `n`: `[array( Hn(X[0]) ), array( Hn(X[1]) ), ...]` + - If `homology_dimensions` was set to `n`: `[array( Hn(X[0]) ), array( Hn(X[1]) ), ...]` - If `homology_dimensions` was set to `[i, j]`: `[[array( Hi(X[0]) ), array( Hj(X[0]) )], [array( Hi(X[1]) ), array( Hj(X[1]) )], ...]` :rtype: list of numpy ndarray of shape (,2) or list of list of numpy ndarray of shape (,2) From f8ecddfac18aa7e6ab3bde0e72cec29a269c3876 Mon Sep 17 00:00:00 2001 From: Vincent Rouvreau Date: Thu, 26 Sep 2024 22:35:52 +0200 Subject: [PATCH 2/4] make sphinx-autodoc-typehints work as required (cmake, ci, doc) --- .circleci/config.yml | 20 ++++++++----------- .../modules/GUDHI_third_party_libraries.cmake | 1 + src/python/CMakeLists.txt | 5 +++++ src/python/doc/conf.py | 2 +- src/python/doc/installation.rst | 2 ++ 5 files changed, 17 insertions(+), 13 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 6559558c32..1dbd459a57 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,12 +1,11 @@ version: 2.0 jobs: - -### With all third parties + ### With all third parties examples: docker: # cf. https://github.com/GUDHI/gudhi-deploy/blob/main/Dockerfile_for_circleci_image - - image: gudhi/ci_for_gudhi:2024.06.02 + - image: gudhi/ci_for_gudhi:2024.09.01 steps: - checkout - run: @@ -25,7 +24,7 @@ jobs: tests: docker: - - image: gudhi/ci_for_gudhi:2024.06.02 + - image: gudhi/ci_for_gudhi:2024.09.01 steps: - checkout - run: @@ -44,7 +43,7 @@ jobs: debug_tests: docker: - - image: gudhi/ci_for_gudhi:2024.06.02 + - image: gudhi/ci_for_gudhi:2024.09.01 steps: - checkout - run: @@ -63,7 +62,7 @@ jobs: utils: docker: - - image: gudhi/ci_for_gudhi:2024.06.02 + - image: gudhi/ci_for_gudhi:2024.09.01 steps: - checkout - run: @@ -82,7 +81,7 @@ jobs: python: docker: - - image: gudhi/ci_for_gudhi:2024.06.02 + - image: gudhi/ci_for_gudhi:2024.09.01 resource_class: large # Delaunay complex requires about 5 Gb of RAM to compile steps: - checkout @@ -94,7 +93,6 @@ jobs: - run: name: Build and test python module. Generates and tests the python documentation command: | - pip3 install pydata-sphinx-theme mkdir build cd build cmake -DWITH_GUDHI_THIRD_PARTY=OFF -DUSER_VERSION_DIR=version .. @@ -167,8 +165,7 @@ jobs: latexmk -pdf -interaction=nonstopmode test_biblio.tex latexmk -pdf -interaction=nonstopmode test_gudhi_citation.tex - -### With all third parties, except CGAL and Eigen + ### With all third parties, except CGAL and Eigen examples_without_cgal_eigen: docker: @@ -248,8 +245,7 @@ jobs: python3 setup.py build_ext --inplace ctest --output-on-failure - -### With all third parties, except CGAL + ### With all third parties, except CGAL examples_without_cgal: docker: diff --git a/src/cmake/modules/GUDHI_third_party_libraries.cmake b/src/cmake/modules/GUDHI_third_party_libraries.cmake index 6527d0be3c..250401ff3a 100644 --- a/src/cmake/modules/GUDHI_third_party_libraries.cmake +++ b/src/cmake/modules/GUDHI_third_party_libraries.cmake @@ -185,6 +185,7 @@ if (WITH_GUDHI_PYTHON) find_python_module("sphinx_paramlinks") find_python_module("pydata_sphinx_theme") find_python_module("sphinxcontrib.bibtex") + find_python_module("sphinx-autodoc-typehints") find_python_module("networkx") # Specific case for PyKeops on Windows where import fails because it uses fcntl (not available on Windows) if (NOT WIN32) diff --git a/src/python/CMakeLists.txt b/src/python/CMakeLists.txt index 3198461820..4be5ce9602 100644 --- a/src/python/CMakeLists.txt +++ b/src/python/CMakeLists.txt @@ -178,6 +178,11 @@ if(SPHINXCONTRIB.BIBTEX_FOUND) else() disable_python_documentation("sphinxcontrib-bibtex") endif() +if(SPHINX-AUTODOC-TYPEHINTS_FOUND) + add_gudhi_debug_info("sphinx-autodoc-typehints version ${SPHINX-AUTODOC-TYPEHINTS_VERSION}") +else() + disable_python_documentation("sphinx-autodoc-typehints") +endif() if(NETWORKX_FOUND) add_gudhi_debug_info("NetworkX version ${NETWORKX_VERSION}") endif() diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py index 6adf827328..a974c7aee4 100755 --- a/src/python/doc/conf.py +++ b/src/python/doc/conf.py @@ -22,7 +22,7 @@ ] autodoc_class_signature = "separated" -autodoc_typehints = "description" +autodoc_typehints = "none" bibtex_bibfiles = ["../../biblio/bibliography.bib"] diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst index 067b733efb..d3aff7e706 100644 --- a/src/python/doc/installation.rst +++ b/src/python/doc/installation.rst @@ -183,6 +183,7 @@ A complete configuration would be : Sphinx-paramlinks version 0.6.0 pydata_sphinx_theme version 0.15.2 sphinxcontrib-bibtex version 2.6.2 + sphinx-autodoc-typehints version 2.4.4 NetworkX version 3.3 Eigen3 version 3.4.0 Boost version 1.84.0 @@ -204,6 +205,7 @@ Documentation To build the documentation, `sphinx-doc `_, `sphinxcontrib-bibtex `_, +`sphinx-autodoc-typehints `_, `sphinxcontrib-paramlinks `_ and `pydata-sphinx-theme `_ :math:`\geq` 0.8.0 are required. As the documentation is auto-tested, `CGAL`_, `Eigen`_, From 52aa6022583a68c781ce925a904d7870c5206c62 Mon Sep 17 00:00:00 2001 From: Vincent Rouvreau Date: Fri, 27 Sep 2024 12:33:06 +0200 Subject: [PATCH 3/4] code review: switch to google style --- src/python/gudhi/sklearn/rips_persistence.py | 35 ++++++++++---------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/src/python/gudhi/sklearn/rips_persistence.py b/src/python/gudhi/sklearn/rips_persistence.py index b5c643fb1f..ff6bbecba6 100644 --- a/src/python/gudhi/sklearn/rips_persistence.py +++ b/src/python/gudhi/sklearn/rips_persistence.py @@ -54,23 +54,24 @@ def __init__( ): """Constructor for the RipsPersistence class. - :param homology_dimensions: The returned persistence diagrams dimension(s). - Short circuit the use of :class:`~gudhi.representations.preprocessing.DimensionSelector` when only one - dimension matters (in other words, when `homology_dimensions` is an int). - :param threshold: Rips maximal edge length value. Default is +Inf. Ignored if input_type is - 'distance coo_matrix'. - :param input_type: Can be 'point cloud' when inputs are point clouds, 'full distance matrix', - 'lower distance matrix' when inputs are lower triangular distance matrix (can be full square, - but the upper part will not be considered), or 'distance coo_matrix' for a distance matrix in SciPy's - sparse format, which should contain each edge at most once (avoid the symmetric) and no diagonal entry. - Default is 'point cloud'. - :param num_collapses: Specify the number of iterations of - :func:`~gudhi.flag_filtration.edge_collapse.reduce_graph` (edge collapse) to perform on the graph. - Default value is 'auto'. - :param homology_coeff_field: The homology coefficient field. Must be a prime number. Default value is 11. - :param n_jobs: Number of jobs to run in parallel. `None` (default value) means `n_jobs = 1` unless in a - joblib.parallel_backend context. `-1` means using all processors. cf. - https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for more details. + Parameters: + homology_dimensions: The returned persistence diagrams dimension(s). + Short circuit the use of :class:`~gudhi.representations.preprocessing.DimensionSelector` when only one + dimension matters (in other words, when `homology_dimensions` is an int). + threshold: Rips maximal edge length value. Default is +Inf. Ignored if input_type is + 'distance coo_matrix'. + input_type: Can be 'point cloud' when inputs are point clouds, 'full distance matrix', + 'lower distance matrix' when inputs are lower triangular distance matrix (can be full square, + but the upper part will not be considered), or 'distance coo_matrix' for a distance matrix in SciPy's + sparse format, which should contain each edge at most once (avoid the symmetric) and no diagonal entry. + Default is 'point cloud'. + num_collapses: Specify the number of iterations of + :func:`~gudhi.flag_filtration.edge_collapse.reduce_graph` (edge collapse) to perform on the graph. + Default value is 'auto'. + homology_coeff_field: The homology coefficient field. Must be a prime number. Default value is 11. + n_jobs: Number of jobs to run in parallel. `None` (default value) means `n_jobs = 1` unless in a + joblib.parallel_backend context. `-1` means using all processors. cf. + https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for more details. """ self.homology_dimensions = homology_dimensions self.threshold = threshold From 20c7761a60a3e5ddf48f8aaaad898d773223f415 Mon Sep 17 00:00:00 2001 From: Vincent Rouvreau Date: Mon, 30 Sep 2024 09:42:15 +0200 Subject: [PATCH 4/4] code review: optimize some options --- src/python/doc/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py index a974c7aee4..5738d04eab 100755 --- a/src/python/doc/conf.py +++ b/src/python/doc/conf.py @@ -22,7 +22,10 @@ ] autodoc_class_signature = "separated" +# cf. https://github.com/tox-dev/sphinx-autodoc-typehints#options autodoc_typehints = "none" +napoleon_use_rtype = True +always_use_bars_union = True bibtex_bibfiles = ["../../biblio/bibliography.bib"]