From b5e9dafc1dc87ca6dbe5882c5def8184067b03d8 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Thu, 6 Jul 2023 14:06:55 +0200 Subject: [PATCH 01/10] Complete source files in doc folder --- doc/Makefile | 20 ++++ doc/api/bp.rst | 34 ++++++ doc/api/index.rst | 11 ++ doc/brainprint.cli.rst | 37 +++++++ doc/brainprint.commands.rst | 21 ++++ doc/brainprint.rst | 42 ++++++++ doc/brainprint.utils.rst | 29 +++++ doc/brainprint.utils.tests.rst | 21 ++++ doc/conf.py | 190 +++++++++++++++++++++++++++++++++ doc/index.rst | 54 ++++++++++ doc/links.inc | 36 +++++++ doc/make.bat | 35 ++++++ doc/modules.rst | 7 ++ doc/references.bib | 34 ++++++ doc/setup.rst | 7 ++ 15 files changed, 578 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/api/bp.rst create mode 100644 doc/api/index.rst create mode 100644 doc/brainprint.cli.rst create mode 100644 doc/brainprint.commands.rst create mode 100644 doc/brainprint.rst create mode 100644 doc/brainprint.utils.rst create mode 100644 doc/brainprint.utils.tests.rst create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/links.inc create mode 100644 doc/make.bat create mode 100644 doc/modules.rst create mode 100644 doc/references.bib create mode 100644 doc/setup.rst diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +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) diff --git a/doc/api/bp.rst b/doc/api/bp.rst new file mode 100644 index 0000000..8e2e218 --- /dev/null +++ b/doc/api/bp.rst @@ -0,0 +1,34 @@ + + +.. toctree:: + :maxdepth: 4 + + brainprint.cli + brainprint.commands + brainprint.utils + + +brainprint.asymmetry module +--------------------------- + +.. automodule:: brainprint.asymmetry + :members: + :undoc-members: + :show-inheritance: + +brainprint.brainprint module +---------------------------- + +.. automodule:: brainprint.brainprint + :members: + :undoc-members: + :show-inheritance: + +brainprint.surfaces module +-------------------------- + +.. automodule:: brainprint.surfaces + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 0000000..f6d26fb --- /dev/null +++ b/doc/api/index.rst @@ -0,0 +1,11 @@ + +API References +============== + +.. toctree:: + :maxdepth: 2 + + bp.rst + + + diff --git a/doc/brainprint.cli.rst b/doc/brainprint.cli.rst new file mode 100644 index 0000000..02e4cd2 --- /dev/null +++ b/doc/brainprint.cli.rst @@ -0,0 +1,37 @@ +brainprint.cli package +====================== + +Submodules +---------- + +brainprint.cli.help\_text module +-------------------------------- + +.. automodule:: brainprint.cli.help_text + :members: + :undoc-members: + :show-inheritance: + +brainprint.cli.parser module +---------------------------- + +.. automodule:: brainprint.cli.parser + :members: + :undoc-members: + :show-inheritance: + +brainprint.cli.utils module +--------------------------- + +.. automodule:: brainprint.cli.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: brainprint.cli + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/brainprint.commands.rst b/doc/brainprint.commands.rst new file mode 100644 index 0000000..cbecdb5 --- /dev/null +++ b/doc/brainprint.commands.rst @@ -0,0 +1,21 @@ +brainprint.commands package +=========================== + +Submodules +---------- + +brainprint.commands.sys\_info module +------------------------------------ + +.. automodule:: brainprint.commands.sys_info + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: brainprint.commands + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/brainprint.rst b/doc/brainprint.rst new file mode 100644 index 0000000..ae8e22b --- /dev/null +++ b/doc/brainprint.rst @@ -0,0 +1,42 @@ + +.. toctree:: + :maxdepth: 4 + + brainprint.cli + brainprint.commands + brainprint.utils + +Submodules +---------- + +brainprint.asymmetry module +--------------------------- + +.. automodule:: brainprint.asymmetry + :members: + :undoc-members: + :show-inheritance: + +brainprint.brainprint module +---------------------------- + +.. automodule:: brainprint.brainprint + :members: + :undoc-members: + :show-inheritance: + +brainprint.surfaces module +-------------------------- + +.. automodule:: brainprint.surfaces + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: brainprint + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/brainprint.utils.rst b/doc/brainprint.utils.rst new file mode 100644 index 0000000..883abcd --- /dev/null +++ b/doc/brainprint.utils.rst @@ -0,0 +1,29 @@ +brainprint.utils package +======================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + brainprint.utils.tests + +Submodules +---------- + +brainprint.utils.utils module +----------------------------- + +.. automodule:: brainprint.utils.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: brainprint.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/brainprint.utils.tests.rst b/doc/brainprint.utils.tests.rst new file mode 100644 index 0000000..b18516e --- /dev/null +++ b/doc/brainprint.utils.tests.rst @@ -0,0 +1,21 @@ +brainprint.utils.tests package +============================== + +Submodules +---------- + +brainprint.utils.tests.test\_config module +------------------------------------------ + +.. automodule:: brainprint.utils.tests.test_config + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: brainprint.utils.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..0b80dc1 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,190 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import inspect +from datetime import date + + +import brainprint + +from sphinx_gallery.sorting import FileNameSortKey + + +# Setting absolute path to the previous directory +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'BrainPrint' +author = 'Martin Reuter' +copyright = f"{date.today().year}, {author}" +release = brainprint.__version__ +package = brainprint.__name__ +gh_url = "https://github.com/Deep-MI/BrainPrint" + + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = "5.0" + +# The document name of the “root” document, that is, the document that contains +# the root toctree directive. +root_doc = "index" + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autosummary", + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx_tabs.tabs", + "sphinx.ext.intersphinx", + "sphinxcontrib.bibtex", + "sphinx_copybutton", + "sphinx_issues", + "sphinx.ext.todo", + "sphinx.ext.viewcode" + ] +# "sphinx_gallery.gen_gallery", + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', "**.ipynb_checkpoints", "tutorials/examples/README.rst"] + +# Sphinx will warn about all references where the target cannot be found. +nitpicky = True +nitpick_ignore = [] + +# A list of ignored prefixes for module index sorting. +modindex_common_prefix = [f"{package}."] + +# The name of a reST role (builtin or Sphinx extension) to use as the default +# role, that is, for text marked up `like this`. This can be set to 'py:obj' to +# make `filter` a cross-reference to the Python function “filter”. +default_role = "py:obj" + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'furo' +html_static_path = ['_static'] +html_static_path = ["_static"] +html_title = project +html_show_sphinx = False + + +# Documentation to change footer icons: +# https://pradyunsg.me/furo/customisation/footer/#changing-footer-icons +html_theme_options = { + "footer_icons": [ + { + "name": "GitHub", + "url": gh_url, + "html": """ + + + + """, + "class": "", + }, + ], +} + +# -- autosummary ------------------------------------------------------------- +autosummary_generate = True + +# -- autodoc ----------------------------------------------------------------- +autodoc_typehints = "none" +autodoc_member_order = "groupwise" +autodoc_warningiserror = True +autoclass_content = "class" + +# -- intersphinx ------------------------------------------------------------- +intersphinx_mapping = { + "matplotlib": ("https://matplotlib.org/stable", None), + "mne": ("https://mne.tools/stable/", None), + "numpy": ("https://numpy.org/doc/stable", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), + "python": ("https://docs.python.org/3", None), + "scipy": ("https://docs.scipy.org/doc/scipy", None), + "sklearn": ("https://scikit-learn.org/stable/", None), +} +intersphinx_timeout = 5 + + +# -- sphinxcontrib-bibtex ---------------------------------------------------- +bibtex_bibfiles = ["./references.bib"] + +# -- sphinx.ext.linkcode ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html + + +def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: + """Determine the URL corresponding to a Python object. + + Parameters + ---------- + domain : str + One of 'py', 'c', 'cpp', 'javascript'. + info : dict + With keys "module" and "fullname". + + Returns + ------- + url : str | None + The code URL. If None, no link is added. + """ + if domain != "py": + return None # only document python objects + + # retrieve pyobject and file + try: + module = import_module(info["module"]) + pyobject = module + for elt in info["fullname"].split("."): + pyobject = getattr(pyobject, elt) + fname = inspect.getsourcefile(pyobject).replace("\\", "/") + except Exception: + # Either the object could not be loaded or the file was not found. + # For instance, properties will raise. + return None + + # retrieve start/stop lines + source, start_line = inspect.getsourcelines(pyobject) + lines = "L%d-L%d" % (start_line, start_line + len(source) - 1) + + # create URL + if "dev" in release: + branch = "main" + else: + return None # alternatively, link to a maint/version branch + fname = fname.rsplit(f"/{package}/")[1] + url = f"{gh_url}/blob/{branch}/{package}/{fname}#{lines}" + return url + +# # -- sphinx-gallery ---------------------------------------------------------- +# sphinx_gallery_conf = { +# "backreferences_dir": "generated/backreferences", +# "doc_module": (f"{package}",), +# "examples_dirs": ["/home/ashrafo/BrainPrint_local/brainprint"], +# "exclude_implicit_doc": {}, # set +# "filename_pattern": r"\d{2}_", +# "gallery_dirs": ["generated/examples"], +# "line_numbers": False, +# "plot_gallery": True, +# "reference_url": {f"{package}": None}, +# "remove_config_comments": True, +# "show_memory": True, +# "within_subsection_order": FileNameSortKey, +# } + + + # "examples_dirs": ["../examples"], + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..8cf9768 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,54 @@ + + +.. include:: ./links.inc + + +.. BrainPrint documentation master file, created by + sphinx-quickstart on Wed Jun 28 14:26:56 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +**BrainPrint** +============== + + +This is the `brainprint python package `_ a derivative of the original BrainPrint-legacy scripts, +with the primary goal to provide a Python-only version, to integrate the LaPy package, +and to remove dependencies on third-party software (shapeDNA-* binaries, gmsh, meshfix). +As a result, some functionality of the original BrainPrint-legacy scripts is no longer maintained +(currently no support of tetrahedral meshes and no support of cortical parcellations or label files). + +The github project directory is available on `BrainPrint GitHub repository `_. + +.. toctree:: + :maxdepth: 2 + + api/index + + +Install +------- + +BrainPrint is available on `PyPI `_ + + +To install brainprint, run the following command: + +.. code-block:: bash + + python3 -m pip install brainprint + + +License +------- + +``BrainPrint`` is licensed under the `MIT license`_. + +A full copy of the license can be found on `GitHub `_. + +.. Indices and tables +.. ================== + +.. * :ref:`genindex` +.. * :ref:`modindex` +.. * :ref:`search` diff --git a/doc/links.inc b/doc/links.inc new file mode 100644 index 0000000..0794c60 --- /dev/null +++ b/doc/links.inc @@ -0,0 +1,36 @@ +.. This (-*- rst -*-) format file contains commonly used link targets and name + substitutions. It may be included in many files, therefore it should only + contain link targets and name substitutions. Try grepping for "^\.\. _" to + find plausible candidates for this list. + +.. NOTE: reST targets are + __not_case_sensitive__, so only one target definition is needed for: + nipy, NIPY, Nipy, etc... + + +.. project + +.. _project pypi: https://pypi.org/project/lapy/ +.. _project conda: https://anaconda.org/conda-forge/lapy +.. _project github: https://github.com/Deep-MI/BrainPrint +.. _project license: https://github.com/Deep-MI/BrainPrint/blob/main/LICENSE +.. _project brainprint: https://pypi.org/project/brainprint/ + +.. license + +.. _MIT license: https://opensource.org/licenses/MIT + + +.. numpy + +.. _numpy: https://numpy.org/ + + +.. sklearn + +.. _scikit-learn: https://scikit-learn.org/stable/ + + +.. scipy + +.. _scipy: https://scipy.org/ diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/modules.rst b/doc/modules.rst new file mode 100644 index 0000000..5bee895 --- /dev/null +++ b/doc/modules.rst @@ -0,0 +1,7 @@ +brainprint +========== + +.. toctree:: + :maxdepth: 4 + + brainprint diff --git a/doc/references.bib b/doc/references.bib new file mode 100644 index 0000000..b2a95da --- /dev/null +++ b/doc/references.bib @@ -0,0 +1,34 @@ +@article{conformal_parameterization_2020, + author = {Choi, Gary P. T. and Leung-Liu, Yusan and Gu, Xianfeng and Lui, Lok Ming}, + doi = {10.1137/19M125337X}, + journal = {SIAM Journal on Imaging Sciences}, + number = {3}, + pages = {1049-1083}, + title = {Parallelizable Global Conformal Parameterization of Simply-Connected Surfaces via Partial Welding}, + volume = {13}, + year = {2020} +} + +@article{numpy_2020, + author = {Harris, Charles R. and Millman, K. Jarrod and van der Walt, Stéfan J. and Gommers, Ralf and Virtanen, Pauli and Cournapeau, David and Wieser, Eric and Taylor, Julian and Berg, Sebastian and Smith, Nathaniel J. and Kern, Robert and Picus, Matti and Hoyer, Stephan and van Kerkwijk, Marten H. and Brett, Matthew and Haldane, Allan and del Río, Jaime Fernández and Wiebe, Mark and Peterson, Pearu and Gérard-Marchant, Pierre and Sheppard, Kevin and Reddy, Tyler and Weckesser, Warren and Abbasi, Hameer and Gohlke, Christoph and Oliphant, Travis E.}, + doi = {10.1038/s41586-020-2649-2}, + journal = {Nature}, + month = {September}, + number = {7825}, + pages = {357--362}, + title = {Array programming with {NumPy}}, + volume = {585}, + year = {2020} +} + +@article{scipy_2020, + author = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and van der Walt, Stéfan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, C J and Polat, İlhan and Feng, Yu and Moore, Eric W. and VanderPlas, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Antônio H. and Pedregosa, Fabian and van Mulbregt, Paul and {SciPy 1.0 Contributors} and Vijaykumar, Aditya and Bardelli, Alessandro Pietro and Rothberg, Alex and Hilboll, Andreas and Kloeckner, Andreas and Scopatz, Anthony and Lee, Antony and Rokem, Ariel and Woods, C. Nathan and Fulton, Chad and Masson, Charles and Häggström, Christian and Fitzgerald, Clark and Nicholson, David A. and Hagen, David R. and Pasechnik, Dmitrii V. and Olivetti, Emanuele and Martin, Eric and Wieser, Eric and Silva, Fabrice and Lenders, Felix and Wilhelm, Florian and Young, G. and Price, Gavin A. and Ingold, Gert-Ludwig and Allen, Gregory E. and Lee, Gregory R. and Audren, Hervé and Probst, Irvin and Dietrich, Jörg P. and Silterra, Jacob and Webber, James T and Slavič, Janko and Nothman, Joel and Buchner, Johannes and Kulick, Johannes and Schönberger, Johannes L. and de Miranda Cardoso, José Vinícius and Reimer, Joscha and Harrington, Joseph and Rodríguez, Juan Luis Cano and Nunez-Iglesias, Juan and Kuczynski, Justin and Tritz, Kevin and Thoma, Martin and Newville, Matthew and Kümmerer, Matthias and Bolingbroke, Maximilian and Tartre, Michael and Pak, Mikhail and Smith, Nathaniel J. and Nowaczyk, Nikolai and Shebanov, Nikolay and Pavlyk, Oleksandr and Brodtkorb, Per A. and Lee, Perry and McGibbon, Robert T. and Feldbauer, Roman and Lewis, Sam and Tygier, Sam and Sievert, Scott and Vigna, Sebastiano and Peterson, Stefan and More, Surhud and Pudlik, Tadeusz and Oshima, Takuya and Pingel, Thomas J. and Robitaille, Thomas P. and Spura, Thomas and Jones, Thouis R. and Cera, Tim and Leslie, Tim and Zito, Tiziano and Krauss, Tom and Upadhyay, Utkarsh and Halchenko, Yaroslav O. and Vázquez-Baeza, Yoshiki}, + doi = {10.1038/s41592-019-0686-2}, + journal = {Nature Methods}, + month = {March}, + number = {3}, + pages = {261--272}, + title = {{SciPy} 1.0: fundamental algorithms for scientific computing in {Python}}, + volume = {17}, + year = {2020} +} diff --git a/doc/setup.rst b/doc/setup.rst new file mode 100644 index 0000000..552eb49 --- /dev/null +++ b/doc/setup.rst @@ -0,0 +1,7 @@ +setup module +============ + +.. automodule:: setup + :members: + :undoc-members: + :show-inheritance: From bbbcc9d262cd49d44eff6b868a90b4d52ff168c9 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 19 Jul 2023 15:39:14 +0200 Subject: [PATCH 02/10] Sphnix documentations with autodoc method --- doc/_templates/autosummary/class.rst | 10 ++ doc/_templates/autosummary/function.rst | 8 + doc/_templates/autosummary/module.rst | 6 + doc/api/bp.rst | 34 ---- doc/api/brainprint.classes.rst | 11 ++ doc/api/brainprint.modules.rst | 13 ++ doc/api/index.rst | 8 +- doc/brainprint.cli.rst | 37 ---- doc/brainprint.commands.rst | 21 --- doc/brainprint.rst | 42 ----- doc/brainprint.utils.rst | 29 --- doc/brainprint.utils.tests.rst | 21 --- doc/conf.py | 225 ++++++++++++++++-------- doc/index.rst | 19 +- doc/modules.rst | 7 - doc/setup.rst | 7 - 16 files changed, 211 insertions(+), 287 deletions(-) create mode 100644 doc/_templates/autosummary/class.rst create mode 100644 doc/_templates/autosummary/function.rst create mode 100644 doc/_templates/autosummary/module.rst delete mode 100644 doc/api/bp.rst create mode 100644 doc/api/brainprint.classes.rst create mode 100644 doc/api/brainprint.modules.rst delete mode 100644 doc/brainprint.cli.rst delete mode 100644 doc/brainprint.commands.rst delete mode 100644 doc/brainprint.rst delete mode 100644 doc/brainprint.utils.rst delete mode 100644 doc/brainprint.utils.tests.rst delete mode 100644 doc/modules.rst delete mode 100644 doc/setup.rst diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst new file mode 100644 index 0000000..3322b32 --- /dev/null +++ b/doc/_templates/autosummary/class.rst @@ -0,0 +1,10 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :inherited-members: + +.. minigallery:: {{ fullname }} + :add-heading: diff --git a/doc/_templates/autosummary/function.rst b/doc/_templates/autosummary/function.rst new file mode 100644 index 0000000..cdbecc4 --- /dev/null +++ b/doc/_templates/autosummary/function.rst @@ -0,0 +1,8 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} + +.. minigallery:: {{ fullname }} + :add-heading: diff --git a/doc/_templates/autosummary/module.rst b/doc/_templates/autosummary/module.rst new file mode 100644 index 0000000..13a2c27 --- /dev/null +++ b/doc/_templates/autosummary/module.rst @@ -0,0 +1,6 @@ +{{ fullname }} +{{ underline }} + +.. automodule:: {{ fullname }} + :members: + diff --git a/doc/api/bp.rst b/doc/api/bp.rst deleted file mode 100644 index 8e2e218..0000000 --- a/doc/api/bp.rst +++ /dev/null @@ -1,34 +0,0 @@ - - -.. toctree:: - :maxdepth: 4 - - brainprint.cli - brainprint.commands - brainprint.utils - - -brainprint.asymmetry module ---------------------------- - -.. automodule:: brainprint.asymmetry - :members: - :undoc-members: - :show-inheritance: - -brainprint.brainprint module ----------------------------- - -.. automodule:: brainprint.brainprint - :members: - :undoc-members: - :show-inheritance: - -brainprint.surfaces module --------------------------- - -.. automodule:: brainprint.surfaces - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/api/brainprint.classes.rst b/doc/api/brainprint.classes.rst new file mode 100644 index 0000000..3a37a78 --- /dev/null +++ b/doc/api/brainprint.classes.rst @@ -0,0 +1,11 @@ +classes +======= + + +.. currentmodule:: brainprint + +.. autosummary:: + :toctree: generated/ + + brainprint + diff --git a/doc/api/brainprint.modules.rst b/doc/api/brainprint.modules.rst new file mode 100644 index 0000000..2f0d54b --- /dev/null +++ b/doc/api/brainprint.modules.rst @@ -0,0 +1,13 @@ +Modules +======= + + +.. currentmodule:: brainprint + +.. autosummary:: + :toctree: generated/ + + asymmetry + surfaces + + diff --git a/doc/api/index.rst b/doc/api/index.rst index f6d26fb..f72b352 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,11 +1,9 @@ - API References ============== + .. toctree:: :maxdepth: 2 - bp.rst - - - + brainprint.modules.rst + brainprint.classes diff --git a/doc/brainprint.cli.rst b/doc/brainprint.cli.rst deleted file mode 100644 index 02e4cd2..0000000 --- a/doc/brainprint.cli.rst +++ /dev/null @@ -1,37 +0,0 @@ -brainprint.cli package -====================== - -Submodules ----------- - -brainprint.cli.help\_text module --------------------------------- - -.. automodule:: brainprint.cli.help_text - :members: - :undoc-members: - :show-inheritance: - -brainprint.cli.parser module ----------------------------- - -.. automodule:: brainprint.cli.parser - :members: - :undoc-members: - :show-inheritance: - -brainprint.cli.utils module ---------------------------- - -.. automodule:: brainprint.cli.utils - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: brainprint.cli - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/brainprint.commands.rst b/doc/brainprint.commands.rst deleted file mode 100644 index cbecdb5..0000000 --- a/doc/brainprint.commands.rst +++ /dev/null @@ -1,21 +0,0 @@ -brainprint.commands package -=========================== - -Submodules ----------- - -brainprint.commands.sys\_info module ------------------------------------- - -.. automodule:: brainprint.commands.sys_info - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: brainprint.commands - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/brainprint.rst b/doc/brainprint.rst deleted file mode 100644 index ae8e22b..0000000 --- a/doc/brainprint.rst +++ /dev/null @@ -1,42 +0,0 @@ - -.. toctree:: - :maxdepth: 4 - - brainprint.cli - brainprint.commands - brainprint.utils - -Submodules ----------- - -brainprint.asymmetry module ---------------------------- - -.. automodule:: brainprint.asymmetry - :members: - :undoc-members: - :show-inheritance: - -brainprint.brainprint module ----------------------------- - -.. automodule:: brainprint.brainprint - :members: - :undoc-members: - :show-inheritance: - -brainprint.surfaces module --------------------------- - -.. automodule:: brainprint.surfaces - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: brainprint - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/brainprint.utils.rst b/doc/brainprint.utils.rst deleted file mode 100644 index 883abcd..0000000 --- a/doc/brainprint.utils.rst +++ /dev/null @@ -1,29 +0,0 @@ -brainprint.utils package -======================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - brainprint.utils.tests - -Submodules ----------- - -brainprint.utils.utils module ------------------------------ - -.. automodule:: brainprint.utils.utils - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: brainprint.utils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/brainprint.utils.tests.rst b/doc/brainprint.utils.tests.rst deleted file mode 100644 index b18516e..0000000 --- a/doc/brainprint.utils.tests.rst +++ /dev/null @@ -1,21 +0,0 @@ -brainprint.utils.tests package -============================== - -Submodules ----------- - -brainprint.utils.tests.test\_config module ------------------------------------------- - -.. automodule:: brainprint.utils.tests.test_config - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: brainprint.utils.tests - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/conf.py b/doc/conf.py index 0b80dc1..339f643 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -3,32 +3,28 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -import inspect -from datetime import date +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -import brainprint +import inspect +from datetime import date +from importlib import import_module +from typing import Dict, Optional from sphinx_gallery.sorting import FileNameSortKey +import brainprint -# Setting absolute path to the previous directory -import os -import sys - -sys.path.insert(0, os.path.abspath("..")) - - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = 'BrainPrint' -author = 'Martin Reuter' +project = "Brainprint" +author = "Martin Reuter" copyright = f"{date.today().year}, {author}" release = brainprint.__version__ package = brainprint.__name__ gh_url = "https://github.com/Deep-MI/BrainPrint" +# -- general configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # If your documentation needs a minimal Sphinx version, state it here. needs_sphinx = "5.0" @@ -38,27 +34,31 @@ root_doc = "index" -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = ["sphinx.ext.autosummary", - "sphinx.ext.autodoc", +extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", - "sphinx_tabs.tabs", + "sphinx.ext.autosummary", "sphinx.ext.intersphinx", + "sphinx.ext.linkcode", + "sphinxcontrib.napoleon", "sphinxcontrib.bibtex", "sphinx_copybutton", - "sphinx_issues", - "sphinx.ext.todo", - "sphinx.ext.viewcode" - ] -# "sphinx_gallery.gen_gallery", + "sphinx_design", + "sphinx_gallery.gen_gallery", + "IPython.sphinxext.ipython_console_highlighting", + "numpydoc", + # "sphinx.ext.todo", + # "sphinx.ext.viewcode", + ] + +# numpydoc_class_members_toctree = True + templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', "**.ipynb_checkpoints", "tutorials/examples/README.rst"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints", "tutorials/examples/README.rst"] # Sphinx will warn about all references where the target cannot be found. -nitpicky = True +#nitpicky = True +nitpicky = False nitpick_ignore = [] # A list of ignored prefixes for module index sorting. @@ -69,13 +69,11 @@ # make `filter` a cross-reference to the Python function “filter”. default_role = "py:obj" - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'furo' html_static_path = ['_static'] -html_static_path = ["_static"] html_title = project html_show_sphinx = False @@ -97,6 +95,7 @@ ], } + # -- autosummary ------------------------------------------------------------- autosummary_generate = True @@ -106,6 +105,8 @@ autodoc_warningiserror = True autoclass_content = "class" + + # -- intersphinx ------------------------------------------------------------- intersphinx_mapping = { "matplotlib": ("https://matplotlib.org/stable", None), @@ -116,64 +117,119 @@ "scipy": ("https://docs.scipy.org/doc/scipy", None), "sklearn": ("https://scikit-learn.org/stable/", None), } + intersphinx_timeout = 5 +# -- sphinx-issues ----------------------------------------------------------- +issues_github_path = gh_url.split("https://github.com/")[-1] + +# -- autosectionlabels ------------------------------------------------------- +autosectionlabel_prefix_document = True + # -- sphinxcontrib-bibtex ---------------------------------------------------- bibtex_bibfiles = ["./references.bib"] + # -- sphinx.ext.linkcode ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html -def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: - """Determine the URL corresponding to a Python object. - - Parameters - ---------- - domain : str - One of 'py', 'c', 'cpp', 'javascript'. - info : dict - With keys "module" and "fullname". - - Returns - ------- - url : str | None - The code URL. If None, no link is added. - """ - if domain != "py": - return None # only document python objects - - # retrieve pyobject and file - try: - module = import_module(info["module"]) - pyobject = module - for elt in info["fullname"].split("."): - pyobject = getattr(pyobject, elt) - fname = inspect.getsourcefile(pyobject).replace("\\", "/") - except Exception: - # Either the object could not be loaded or the file was not found. - # For instance, properties will raise. - return None - - # retrieve start/stop lines - source, start_line = inspect.getsourcelines(pyobject) - lines = "L%d-L%d" % (start_line, start_line + len(source) - 1) - # create URL - if "dev" in release: - branch = "main" +# def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: +# """Determine the URL corresponding to a Python object. + +# Parameters +# ---------- +# domain : str +# One of 'py', 'c', 'cpp', 'javascript'. +# info : dict +# With keys "module" and "fullname". + +# Returns +# ------- +# url : str | None +# The code URL. If None, no link is added. +# """ +# if domain != "py": +# return None # only document python objects + +# # retrieve pyobject and file +# try: +# module = import_module(info["module"]) +# pyobject = module +# for elt in info["fullname"].split("."): +# pyobject = getattr(pyobject, elt) +# fname = inspect.getsourcefile(pyobject).replace("\\", "/") +# except Exception: +# # Either the object could not be loaded or the file was not found. +# # For instance, properties will raise. +# return None + +# # retrieve start/stop lines +# source, start_line = inspect.getsourcelines(pyobject) +# lines = "L%d-L%d" % (start_line, start_line + len(source) - 1) + +# # create URL +# if "dev" in release: +# branch = "main" +# else: +# return None # alternatively, link to a maint/version branch +# fname = fname.rsplit(f"/{package}/")[1] +# url = f"{gh_url}/blob/{branch}/{package}/{fname}#{lines}" +# return url + +# using this method to link github source code as the above method was working with +# brain print project +from urllib.parse import quote + + +def linkcode_resolve(domain, info): + if domain != 'py': + return None + if not info['module']: + return None + + # Replace periods with slashes in the module path + filename = quote(info['module'].replace('.', '/')) + if not filename.startswith("tests"): + # Add the 'src/' prefix to the filename + filename = "/" + filename + + if "fullname" in info: + anchor = info["fullname"] + anchor = "#:~:text=" + quote(anchor.split(".")[-1]) else: - return None # alternatively, link to a maint/version branch - fname = fname.rsplit(f"/{package}/")[1] - url = f"{gh_url}/blob/{branch}/{package}/{fname}#{lines}" - return url + anchor = "" + + # Replace with the actual GitHub repository URL + gh_url = "https://github.com/Deep-MI/BrainPrint" # Replace with your repository URL + result = f"{gh_url}/blob/master/{filename}.py{anchor}" + return result + + + +# -- sphinx-gallery ---------------------------------------------------------- +sphinx_gallery_conf = { + "backreferences_dir": "/home/ashrafo/BrainPrint_local_automethod/doc/generated/backreferences", + "doc_module": (f"{package}",), + "examples_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], + "exclude_implicit_doc": {}, # set + "filename_pattern": r"\d{2}_", + "gallery_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], + "line_numbers": False, + "plot_gallery": True, + "reference_url": {f"{package}": None}, + "remove_config_comments": True, + "show_memory": True, + # "within_subsection_order": FileNameSortKey, +} # # -- sphinx-gallery ---------------------------------------------------------- # sphinx_gallery_conf = { # "backreferences_dir": "generated/backreferences", # "doc_module": (f"{package}",), -# "examples_dirs": ["/home/ashrafo/BrainPrint_local/brainprint"], +# "examples_dirs": ["../examples"], # "exclude_implicit_doc": {}, # set # "filename_pattern": r"\d{2}_", # "gallery_dirs": ["generated/examples"], @@ -186,5 +242,30 @@ def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: # } - # "examples_dirs": ["../examples"], + +import os + +# -- make sure pandoc gets installed ----------------------------------------- +from inspect import getsourcefile + +# Get path to directory containing this file, conf.py. +DOCS_DIRECTORY = os.path.dirname(os.path.abspath(getsourcefile(lambda: 0))) + +def ensure_pandoc_installed(_): + import pypandoc + + # Download pandoc if necessary. If pandoc is already installed and on + # the PATH, the installed version will be used. Otherwise, we will + # download a copy of pandoc into docs/bin/ and add that to our PATH. + pandoc_dir = os.path.join(DOCS_DIRECTORY, "bin") + # Add dir containing pandoc binary to the PATH environment variable + if pandoc_dir not in os.environ["PATH"].split(os.pathsep): + os.environ["PATH"] += os.pathsep + pandoc_dir + pypandoc.ensure_pandoc_installed( + targetfolder=pandoc_dir, + delete_installer=True, + ) + +def setup(app): + app.connect("builder-inited", ensure_pandoc_installed) diff --git a/doc/index.rst b/doc/index.rst index 8cf9768..7e9d16c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,3 @@ - - .. include:: ./links.inc @@ -20,11 +18,6 @@ As a result, some functionality of the original BrainPrint-legacy scripts is no The github project directory is available on `BrainPrint GitHub repository `_. -.. toctree:: - :maxdepth: 2 - - api/index - Install ------- @@ -46,9 +39,11 @@ License A full copy of the license can be found on `GitHub `_. -.. Indices and tables -.. ================== +`BrainPrint `_ is licensed under the `MIT license`_. +A full copy of the license can be found `on GitHub `_. -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` + +.. toctree:: + :hidden: + + api/index diff --git a/doc/modules.rst b/doc/modules.rst deleted file mode 100644 index 5bee895..0000000 --- a/doc/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -brainprint -========== - -.. toctree:: - :maxdepth: 4 - - brainprint diff --git a/doc/setup.rst b/doc/setup.rst deleted file mode 100644 index 552eb49..0000000 --- a/doc/setup.rst +++ /dev/null @@ -1,7 +0,0 @@ -setup module -============ - -.. automodule:: setup - :members: - :undoc-members: - :show-inheritance: From 9170585876560ec15d80f8a5056fb8d7a1ba8883 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Thu, 20 Jul 2023 09:54:01 +0200 Subject: [PATCH 03/10] Remote absolute path fromsphinx gattery conf --- doc/conf.py | 43 +++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 339f643..95886f8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -209,40 +209,43 @@ def linkcode_resolve(domain, info): -# -- sphinx-gallery ---------------------------------------------------------- -sphinx_gallery_conf = { - "backreferences_dir": "/home/ashrafo/BrainPrint_local_automethod/doc/generated/backreferences", - "doc_module": (f"{package}",), - "examples_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], - "exclude_implicit_doc": {}, # set - "filename_pattern": r"\d{2}_", - "gallery_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], - "line_numbers": False, - "plot_gallery": True, - "reference_url": {f"{package}": None}, - "remove_config_comments": True, - "show_memory": True, - # "within_subsection_order": FileNameSortKey, -} - # # -- sphinx-gallery ---------------------------------------------------------- # sphinx_gallery_conf = { -# "backreferences_dir": "generated/backreferences", +# "backreferences_dir": "/home/ashrafo/BrainPrint_local_automethod/doc/generated/backreferences", # "doc_module": (f"{package}",), -# "examples_dirs": ["../examples"], +# "examples_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], # "exclude_implicit_doc": {}, # set # "filename_pattern": r"\d{2}_", -# "gallery_dirs": ["generated/examples"], +# "gallery_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], # "line_numbers": False, # "plot_gallery": True, # "reference_url": {f"{package}": None}, # "remove_config_comments": True, # "show_memory": True, -# "within_subsection_order": FileNameSortKey, +# # "within_subsection_order": FileNameSortKey, # } +# -- conf.py ---------------------------------------------------------- +# In examples_dirs extension I replaced ../examples with generated/examples +# because it was not able to recognize examples path with knowing the parent folder i.e generated +# -- sphinx-gallery ---------------------------------------------------------- +sphinx_gallery_conf = { + "backreferences_dir": "generated/backreferences", + "doc_module": (f"{package}",), + "examples_dirs": ["generated/examples"], + "exclude_implicit_doc": {}, # set + "filename_pattern": r"\d{2}_", + "gallery_dirs": ["generated/examples"], + "line_numbers": False, + "plot_gallery": True, + "reference_url": {f"{package}": None}, + "remove_config_comments": True, + "show_memory": True, + "within_subsection_order": FileNameSortKey, +} + import os From f0122ea742918636f1303127aed891134dd5c7c2 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Thu, 20 Jul 2023 11:43:58 +0200 Subject: [PATCH 04/10] Index file manually updated as per readme.md file --- doc/index.rst | 135 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 112 insertions(+), 23 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 7e9d16c..53073c2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,46 +1,135 @@ .. include:: ./links.inc -.. BrainPrint documentation master file, created by - sphinx-quickstart on Wed Jun 28 14:26:56 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. image:: https://badge.fury.io/py/brainprint.svg + :target: https://pypi.org/project/brainprint/ -**BrainPrint** -============== +BrainPrint +========== +This is the `brainprint` python package, a derivative of the original `BrainPrint-legacy `_ scripts, +with the primary goal to provide a Python-only version, to integrate the `LaPy `_ package, +and to remove dependencies on third-party software (shapeDNA-* binaries, gmsh, meshfix). +As a result, some functionality of the original BrainPrint-legacy scripts is no longer maintained (currently no support of tetrahedral meshes and no support of cortical parcellations or label files). -This is the `brainprint python package `_ a derivative of the original BrainPrint-legacy scripts, -with the primary goal to provide a Python-only version, to integrate the LaPy package, -and to remove dependencies on third-party software (shapeDNA-* binaries, gmsh, meshfix). -As a result, some functionality of the original BrainPrint-legacy scripts is no longer maintained -(currently no support of tetrahedral meshes and no support of cortical parcellations or label files). +Installation +------------ -The github project directory is available on `BrainPrint GitHub repository `_. +Use the following code to install the latest release of LaPy into your local Python package directory: +.. code-block:: bash -Install -------- + python3 -m pip install brainprint -BrainPrint is available on `PyPI `_ +This will also install the necessary dependencies, e.g. the `LaPy `_ package. +You may need to add your local Python package directory to your $PATH in order to run the scripts. +Usage +----- -To install brainprint, run the following command: +Command Line Interface (CLI) +---------------------------- -.. code-block:: bash +Once installed, the package provides a `brainprint` executable which can be run from the command line. + +The `brainprint` CLI enables per-subject computation of the individual brainprint descriptors. Its usage and options are summarized below; detailed info is available by calling the script without any arguments from the command line. + +brainprint Command-Line Interface +''''''''''''''''''''''''''''''''' + +.. code-block:: sh + + brainprint + --sdir + --sid + [--num ] [--evec] [--skipcortex] + [--norm ] + [--reweight] [--asymmetry] [--outdir ] + [--help] [--more-help] + +Options +''''''' + +``--help`` Show this help message and exit. + +``--more-help`` Show extensive help message and exit. + +Required options +'''''''''''''''' + +``--sid `` Subject ID (FreeSurfer-processed directory inside the subjects directory). + +``--sdir `` FreeSurfer subjects directory. + +Processing directives +''''''''''''''''''''' + +``--num `` Number of eigenvalues/vectors to compute (default: 50). + +``--evec`` Switch on eigenvector computation (default: off). + +``--skipcortex`` Skip cortical surfaces (default: off). - python3 -m pip install brainprint +``--norm `` Switch on eigenvalue normalization; will be either surface, volume, or determined by the geometry of the object. Use "none" or leave out entirely to skip normalization. +``--reweight`` Switch on eigenvalue reweighting (default: off). -License +``--asymmetry`` Perform left-right asymmetry calculation (default: off). + +``--cholmod`` Switch on use of (faster) Cholesky decomposition instead of (slower) LU decomposition (default: off). May require manual install of scikit-sparse package. + +Output parameters +''''''''''''''''' + +``--outdir=OUTDIR`` Output directory (default: //brainprint). + +``--keep-temp`` Whether to keep the temporary files directory or not (default: False). + + +Python Package +-------------- + +`brainprint` can also be run within a pure Python environment, i.e. installed and imported as a Python package. E.g.: + +.. code-block:: python + + from brainprint import Brainprint + + subjects_dir = "/path/to/freesurfer/subjects_dir/" + subject_id = "42" + + bp = Brainprint(subjects_dir=subjects_dir, asymmetry=True, keep_eigenvectors=True) + results = bp.run(subject_id=subject_id) + results + {"eigenvalues": PosixPath("/path/to/freesurfer/subjects_dir/subject_id/brainprint/subject_id.brainprint.csv"), + "eigenvectors": PosixPath("/path/to/freesurfer/subjects_dir/subject_id/brainprint/eigenvectors"), + "distances": PosixPath("/path/to/freesurfer/subjects_dir/subject_id/brainprint/subject_id.brainprint.asymmetry.csv")} + + +Output +------ +The script will create an output directory that contains a CSV table with +values (in that order) for the area, volume, and first n eigenvalues per each +FreeSurfer structure. An additional output file will be created if the +asymmetry calculation is performed and/or for the eigenvectors (CLI `--evecs` flag or `keep_eigenvectors` on class initialization). + +Changes ------- -``BrainPrint`` is licensed under the `MIT license`_. +There are some changes in functionality in comparison to the original `BrainPrint `_ scripts: + +- Currently, there is no support for tetrahedral meshes. +- Currently, there is no support for analyses of cortical parcellation or label files. +- No more Python 2.x compatibility. + +References +---------- + +If you use this software for a publication, please cite: -A full copy of the license can be found on `GitHub `_. +[1] BrainPrint: a discriminative characterization of brain morphology. Wachinger C, Golland P, Kremen W, Fischl B, Reuter M. Neuroimage. 2015;109:232-48. `http://dx.doi.org/10.1016/j.neuroimage.2015.01.032 `_ `PubMed `_ -`BrainPrint `_ is licensed under the `MIT license`_. -A full copy of the license can be found `on GitHub `_. +[2] Laplace-Beltrami spectra as 'Shape-DNA' of surfaces and solids. Reuter M, Wolter F-E, Peinecke N. Computer-Aided Design. 2006;38:342-366. `http://dx.doi.org/10.1016/j.cad.2005.10.011 `_ .. toctree:: From f957a5e9de230321229089b543767ffbf6fc3669 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 26 Jul 2023 15:15:33 +0200 Subject: [PATCH 05/10] conf.py file updated --- doc/conf.py | 102 +++++++++++++++++++--------------------------------- 1 file changed, 37 insertions(+), 65 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 95886f8..0f88a6d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -16,13 +16,12 @@ import brainprint -project = "Brainprint" +project = "brainprint" author = "Martin Reuter" copyright = f"{date.today().year}, {author}" release = brainprint.__version__ package = brainprint.__name__ gh_url = "https://github.com/Deep-MI/BrainPrint" - # -- general configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -39,17 +38,36 @@ "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.linkcode", - "sphinxcontrib.napoleon", + # "sphinxcontrib.napoleon", "sphinxcontrib.bibtex", "sphinx_copybutton", "sphinx_design", - "sphinx_gallery.gen_gallery", + # "sphinx_gallery.gen_gallery", "IPython.sphinxext.ipython_console_highlighting", "numpydoc", # "sphinx.ext.todo", # "sphinx.ext.viewcode", + # "myst_parser", ] + +# myst_enable_extensions = [ +# "amsmath", +# "attrs_inline", +# "colon_fence", +# "deflist", +# "dollarmath", +# "fieldlist", +# "html_admonition", +# "html_image", +# "linkify", +# "replacements", +# "smartquotes", +# "strikethrough", +# "substitution", +# "tasklist", +# ] +# myst_heading_anchors = 2 # numpydoc_class_members_toctree = True @@ -131,53 +149,7 @@ bibtex_bibfiles = ["./references.bib"] -# -- sphinx.ext.linkcode ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html - - - -# def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: -# """Determine the URL corresponding to a Python object. - -# Parameters -# ---------- -# domain : str -# One of 'py', 'c', 'cpp', 'javascript'. -# info : dict -# With keys "module" and "fullname". - -# Returns -# ------- -# url : str | None -# The code URL. If None, no link is added. -# """ -# if domain != "py": -# return None # only document python objects - -# # retrieve pyobject and file -# try: -# module = import_module(info["module"]) -# pyobject = module -# for elt in info["fullname"].split("."): -# pyobject = getattr(pyobject, elt) -# fname = inspect.getsourcefile(pyobject).replace("\\", "/") -# except Exception: -# # Either the object could not be loaded or the file was not found. -# # For instance, properties will raise. -# return None - -# # retrieve start/stop lines -# source, start_line = inspect.getsourcelines(pyobject) -# lines = "L%d-L%d" % (start_line, start_line + len(source) - 1) - -# # create URL -# if "dev" in release: -# branch = "main" -# else: -# return None # alternatively, link to a maint/version branch -# fname = fname.rsplit(f"/{package}/")[1] -# url = f"{gh_url}/blob/{branch}/{package}/{fname}#{lines}" -# return url + # using this method to link github source code as the above method was working with # brain print project @@ -231,20 +203,20 @@ def linkcode_resolve(domain, info): # In examples_dirs extension I replaced ../examples with generated/examples # because it was not able to recognize examples path with knowing the parent folder i.e generated # -- sphinx-gallery ---------------------------------------------------------- -sphinx_gallery_conf = { - "backreferences_dir": "generated/backreferences", - "doc_module": (f"{package}",), - "examples_dirs": ["generated/examples"], - "exclude_implicit_doc": {}, # set - "filename_pattern": r"\d{2}_", - "gallery_dirs": ["generated/examples"], - "line_numbers": False, - "plot_gallery": True, - "reference_url": {f"{package}": None}, - "remove_config_comments": True, - "show_memory": True, - "within_subsection_order": FileNameSortKey, -} +# sphinx_gallery_conf = { +# "backreferences_dir": "generated/backreferences", +# "doc_module": (f"{package}",), +# "examples_dirs": ["generated/examples"], +# "exclude_implicit_doc": {}, # set +# "filename_pattern": r"\d{2}_", +# "gallery_dirs": ["generated/examples"], +# "line_numbers": False, +# "plot_gallery": True, +# "reference_url": {f"{package}": None}, +# "remove_config_comments": True, +# "show_memory": True, +# "within_subsection_order": FileNameSortKey, +# } import os From c12843f4dc4c85cf961848888430cb68d9279e41 Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 26 Jul 2023 15:20:32 +0200 Subject: [PATCH 06/10] api referencing modified --- doc/api/brainprint.classes.rst | 11 ----------- doc/api/brainprint.modules.rst | 13 ------------- doc/api/index.rst | 10 ++++++---- 3 files changed, 6 insertions(+), 28 deletions(-) delete mode 100644 doc/api/brainprint.classes.rst delete mode 100644 doc/api/brainprint.modules.rst diff --git a/doc/api/brainprint.classes.rst b/doc/api/brainprint.classes.rst deleted file mode 100644 index 3a37a78..0000000 --- a/doc/api/brainprint.classes.rst +++ /dev/null @@ -1,11 +0,0 @@ -classes -======= - - -.. currentmodule:: brainprint - -.. autosummary:: - :toctree: generated/ - - brainprint - diff --git a/doc/api/brainprint.modules.rst b/doc/api/brainprint.modules.rst deleted file mode 100644 index 2f0d54b..0000000 --- a/doc/api/brainprint.modules.rst +++ /dev/null @@ -1,13 +0,0 @@ -Modules -======= - - -.. currentmodule:: brainprint - -.. autosummary:: - :toctree: generated/ - - asymmetry - surfaces - - diff --git a/doc/api/index.rst b/doc/api/index.rst index f72b352..9eebce1 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,9 +1,11 @@ API References ============== +.. currentmodule:: brainprint -.. toctree:: - :maxdepth: 2 +.. autosummary:: + :toctree: generated/ - brainprint.modules.rst - brainprint.classes + brainprint + asymmetry + surfaces From 20a1154198ebcdb4b12c06ec5d0ae2ac0c6abb6c Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 16 Aug 2023 12:42:45 +0200 Subject: [PATCH 07/10] reference dropped --- doc/references.bib | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index b2a95da..df8e0f3 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -1,14 +1,3 @@ -@article{conformal_parameterization_2020, - author = {Choi, Gary P. T. and Leung-Liu, Yusan and Gu, Xianfeng and Lui, Lok Ming}, - doi = {10.1137/19M125337X}, - journal = {SIAM Journal on Imaging Sciences}, - number = {3}, - pages = {1049-1083}, - title = {Parallelizable Global Conformal Parameterization of Simply-Connected Surfaces via Partial Welding}, - volume = {13}, - year = {2020} -} - @article{numpy_2020, author = {Harris, Charles R. and Millman, K. Jarrod and van der Walt, Stéfan J. and Gommers, Ralf and Virtanen, Pauli and Cournapeau, David and Wieser, Eric and Taylor, Julian and Berg, Sebastian and Smith, Nathaniel J. and Kern, Robert and Picus, Matti and Hoyer, Stephan and van Kerkwijk, Marten H. and Brett, Matthew and Haldane, Allan and del Río, Jaime Fernández and Wiebe, Mark and Peterson, Pearu and Gérard-Marchant, Pierre and Sheppard, Kevin and Reddy, Tyler and Weckesser, Warren and Abbasi, Hameer and Gohlke, Christoph and Oliphant, Travis E.}, doi = {10.1038/s41586-020-2649-2}, From 46c220062f5020bd77415387859f7a449479c3cd Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 16 Aug 2023 12:56:21 +0200 Subject: [PATCH 08/10] conf.py updated --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 0f88a6d..5a550c8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -175,7 +175,7 @@ def linkcode_resolve(domain, info): anchor = "" # Replace with the actual GitHub repository URL - gh_url = "https://github.com/Deep-MI/BrainPrint" # Replace with your repository URL + # gh_url = "https://github.com/Deep-MI/BrainPrint" # Replace with your repository URL result = f"{gh_url}/blob/master/{filename}.py{anchor}" return result From 521ad6c38e62742bd7a2a81c54c11d3c05735fcb Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Wed, 16 Aug 2023 14:58:09 +0200 Subject: [PATCH 09/10] conf.py reformatted using black --- doc/conf.py | 61 +++++++++++++++++++++++++++++---------------------- doc/index.rst | 2 ++ 2 files changed, 37 insertions(+), 26 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 5a550c8..7fb450e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,22 +33,23 @@ root_doc = "index" -extensions = ["sphinx.ext.autodoc", - "sphinx.ext.autosectionlabel", - "sphinx.ext.autosummary", - "sphinx.ext.intersphinx", - "sphinx.ext.linkcode", - # "sphinxcontrib.napoleon", - "sphinxcontrib.bibtex", - "sphinx_copybutton", - "sphinx_design", - # "sphinx_gallery.gen_gallery", - "IPython.sphinxext.ipython_console_highlighting", - "numpydoc", - # "sphinx.ext.todo", - # "sphinx.ext.viewcode", - # "myst_parser", - ] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.linkcode", + # "sphinxcontrib.napoleon", + "sphinxcontrib.bibtex", + "sphinx_copybutton", + "sphinx_design", + # "sphinx_gallery.gen_gallery", + "IPython.sphinxext.ipython_console_highlighting", + "numpydoc", + # "sphinx.ext.todo", + # "sphinx.ext.viewcode", + # "myst_parser", +] # myst_enable_extensions = [ @@ -71,11 +72,17 @@ # numpydoc_class_members_toctree = True -templates_path = ['_templates'] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints", "tutorials/examples/README.rst"] +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "**.ipynb_checkpoints", + "tutorials/examples/README.rst", +] # Sphinx will warn about all references where the target cannot be found. -#nitpicky = True +# nitpicky = True nitpicky = False nitpick_ignore = [] @@ -90,8 +97,8 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'furo' -html_static_path = ['_static'] +html_theme = "furo" +html_static_path = ["_static"] html_title = project html_show_sphinx = False @@ -157,13 +164,13 @@ def linkcode_resolve(domain, info): - if domain != 'py': + if domain != "py": return None - if not info['module']: + if not info["module"]: return None - + # Replace periods with slashes in the module path - filename = quote(info['module'].replace('.', '/')) + filename = quote(info["module"].replace(".", "/")) if not filename.startswith("tests"): # Add the 'src/' prefix to the filename filename = "/" + filename @@ -206,7 +213,7 @@ def linkcode_resolve(domain, info): # sphinx_gallery_conf = { # "backreferences_dir": "generated/backreferences", # "doc_module": (f"{package}",), -# "examples_dirs": ["generated/examples"], +# "examples_dirs": ["generated/examples"], # "exclude_implicit_doc": {}, # set # "filename_pattern": r"\d{2}_", # "gallery_dirs": ["generated/examples"], @@ -227,6 +234,7 @@ def linkcode_resolve(domain, info): # Get path to directory containing this file, conf.py. DOCS_DIRECTORY = os.path.dirname(os.path.abspath(getsourcefile(lambda: 0))) + def ensure_pandoc_installed(_): import pypandoc @@ -242,5 +250,6 @@ def ensure_pandoc_installed(_): delete_installer=True, ) + def setup(app): app.connect("builder-inited", ensure_pandoc_installed) diff --git a/doc/index.rst b/doc/index.rst index 53073c2..e317264 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,7 @@ .. include:: ./links.inc +.. .. literalinclude:: ../README.md +.. :language: markdown .. image:: https://badge.fury.io/py/brainprint.svg :target: https://pypi.org/project/brainprint/ From d34a72390654fbcf87c9ff3d1e661858959fc68e Mon Sep 17 00:00:00 2001 From: engrosamaali91 Date: Thu, 17 Aug 2023 10:56:28 +0200 Subject: [PATCH 10/10] conf.py file modified --- doc/conf.py | 144 ++++++++++++++++++++++------------------------------ 1 file changed, 62 insertions(+), 82 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 7fb450e..144adb1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -12,8 +12,7 @@ from importlib import import_module from typing import Dict, Optional -from sphinx_gallery.sorting import FileNameSortKey - +# from sphinx_gallery.sorting import FileNameSortKey import brainprint project = "brainprint" @@ -52,26 +51,6 @@ ] -# myst_enable_extensions = [ -# "amsmath", -# "attrs_inline", -# "colon_fence", -# "deflist", -# "dollarmath", -# "fieldlist", -# "html_admonition", -# "html_image", -# "linkify", -# "replacements", -# "smartquotes", -# "strikethrough", -# "substitution", -# "tasklist", -# ] -# myst_heading_anchors = 2 -# numpydoc_class_members_toctree = True - - templates_path = ["_templates"] exclude_patterns = [ "_build", @@ -131,7 +110,6 @@ autoclass_content = "class" - # -- intersphinx ------------------------------------------------------------- intersphinx_mapping = { "matplotlib": ("https://matplotlib.org/stable", None), @@ -156,74 +134,76 @@ bibtex_bibfiles = ["./references.bib"] - - # using this method to link github source code as the above method was working with # brain print project -from urllib.parse import quote +# from urllib.parse import quote + + +# def linkcode_resolve(domain, info): +# if domain != "py": +# return None +# if not info["module"]: +# return None +# filename = quote(info["module"].replace(".", "/")) +# if not filename.startswith("tests"): +# filename = "/" + filename -def linkcode_resolve(domain, info): +# if "fullname" in info: +# anchor = info["fullname"] +# anchor = "#:~:text=" + quote(anchor.split(".")[-1]) +# else: +# anchor = "" + +# result = f"{gh_url}/blob/master/{filename}.py{anchor}" +# return result + +# -- sphinx.ext.linkcode ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html + + +def linkcode_resolve(domain: str, info: Dict[str, str]) -> Optional[str]: + """Determine the URL corresponding to a Python object. + + Parameters + ---------- + domain : str + One of 'py', 'c', 'cpp', 'javascript'. + info : dict + With keys "module" and "fullname". + + Returns + ------- + url : str | None + The code URL. If None, no link is added. + """ if domain != "py": - return None - if not info["module"]: + return None # only document python objects + + # retrieve pyobject and file + try: + module = import_module(info["module"]) + pyobject = module + for elt in info["fullname"].split("."): + pyobject = getattr(pyobject, elt) + fname = inspect.getsourcefile(pyobject).replace("\\", "/") + except Exception: + # Either the object could not be loaded or the file was not found. + # For instance, properties will raise. return None - # Replace periods with slashes in the module path - filename = quote(info["module"].replace(".", "/")) - if not filename.startswith("tests"): - # Add the 'src/' prefix to the filename - filename = "/" + filename + # retrieve start/stop lines + source, start_line = inspect.getsourcelines(pyobject) + lines = "L%d-L%d" % (start_line, start_line + len(source) - 1) - if "fullname" in info: - anchor = info["fullname"] - anchor = "#:~:text=" + quote(anchor.split(".")[-1]) + # create URL + if "dev" in release: + branch = "main" else: - anchor = "" - - # Replace with the actual GitHub repository URL - # gh_url = "https://github.com/Deep-MI/BrainPrint" # Replace with your repository URL - result = f"{gh_url}/blob/master/{filename}.py{anchor}" - return result - - - -# # -- sphinx-gallery ---------------------------------------------------------- -# sphinx_gallery_conf = { -# "backreferences_dir": "/home/ashrafo/BrainPrint_local_automethod/doc/generated/backreferences", -# "doc_module": (f"{package}",), -# "examples_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], -# "exclude_implicit_doc": {}, # set -# "filename_pattern": r"\d{2}_", -# "gallery_dirs": ["/home/ashrafo/BrainPrint_local_automethod/doc/generated/examples"], -# "line_numbers": False, -# "plot_gallery": True, -# "reference_url": {f"{package}": None}, -# "remove_config_comments": True, -# "show_memory": True, -# # "within_subsection_order": FileNameSortKey, -# } - -# -- conf.py ---------------------------------------------------------- - - -# In examples_dirs extension I replaced ../examples with generated/examples -# because it was not able to recognize examples path with knowing the parent folder i.e generated -# -- sphinx-gallery ---------------------------------------------------------- -# sphinx_gallery_conf = { -# "backreferences_dir": "generated/backreferences", -# "doc_module": (f"{package}",), -# "examples_dirs": ["generated/examples"], -# "exclude_implicit_doc": {}, # set -# "filename_pattern": r"\d{2}_", -# "gallery_dirs": ["generated/examples"], -# "line_numbers": False, -# "plot_gallery": True, -# "reference_url": {f"{package}": None}, -# "remove_config_comments": True, -# "show_memory": True, -# "within_subsection_order": FileNameSortKey, -# } + return None # alternatively, link to a maint/version branch + fname = fname.rsplit(f"/{package}/")[1] + url = f"{gh_url}/blob/{branch}/{package}/{fname}#{lines}" + return url import os