Sphinx documentation in doc folder (Deep-MI#13)

* Complete source files in doc folder

* Sphnix documentations with autodoc method

* Remote absolute path fromsphinx gattery conf

* Index file manually updated as per readme.md file

* conf.py file updated

* api referencing modified

* reference dropped

* conf.py updated

* conf.py reformatted using black

* conf.py file modified

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)

doc/_templates/autosummary/class.rst

@@ -0,0 +1,10 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/_templates/autosummary/function.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/_templates/autosummary/module.rst

@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+    :members:
+

doc/api/index.rst

@@ -0,0 +1,11 @@
+API References
+==============
+
+.. currentmodule:: brainprint
+
+.. autosummary::
+    :toctree: generated/
+
+    brainprint
+    asymmetry
+    surfaces

doc/conf.py

@@ -0,0 +1,235 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+import inspect
+from datetime import date
+from importlib import import_module
+from typing import Dict, Optional
+
+# from sphinx_gallery.sorting import FileNameSortKey
+import 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
+
+# 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"
+
+
+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",
+]
+
+
+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 = False
+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_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": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "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
+
+
+# -- sphinx-issues -----------------------------------------------------------
+issues_github_path = gh_url.split("https://github.com/")[-1]
+
+# -- autosectionlabels -------------------------------------------------------
+autosectionlabel_prefix_document = True
+
+# -- sphinxcontrib-bibtex ----------------------------------------------------
+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
+
+
+# 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
+
+#     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  # 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
+
+
+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)