Enhance doc link and install

gdmnl · Jun 28, 2024 · 1a74578 · 1a74578
1 parent f8a1989
commit 1a74578
Show file tree

Hide file tree

Showing 13 changed files with 211 additions and 62 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+.ipynb linguist-documentation
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -38,13 +38,13 @@ jobs:
             CHANGELOG.md
             requirements.txt
 
-      - name: Setup packages
+      - name: Install requirement packages
         if: steps.changed-files-specific.outputs.only_changed != 'true'
         uses: ./.github/actions/setup
         with:
           full_install: false
 
-      - name: Install main package
+      - name: Install project packages
         if: steps.changed-files-specific.outputs.only_changed != 'true'
         run: |
           pip install -e .[docs,benchmark]

diff --git a/README.md b/README.md
@@ -2,21 +2,11 @@
 
 <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.1/css/all.css">
 <div align="center">
-  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/">
-    <img src="https://github.com/gdmnl/Spectral-GNN-Benchmark/actions/workflows/docs.yaml/badge.svg" alt="Docs">
-  </a>
-  <a href="https://github.com/gdmnl/Spectral-GNN-Benchmark?tab=MIT-1-ov-file">
-    <img src="https://img.shields.io/github/license/gdmnl/Spectral-GNN-Benchmark" alt="License">
-  </a>
-  <a href="https://github.com/gdmnl/Spectral-GNN-Benchmark/releases/latest">
-    <img src="https://img.shields.io/github/v/release/gdmnl/Spectral-GNN-Benchmark?include_prereleases" alt="Contrib">
-  </a>
-  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/_tutorial/installation.html">
-    <img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fgdmnl%2FSpectral-GNN-Benchmark%2Fmain%2Fpyproject.toml&logo=python&label=Python" alt="Python">
-  </a>
-  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/_tutorial/installation.html">
-    <img src="https://img.shields.io/badge/PyTorch->=2.0-FF6F00?logo=pytorch" alt="PyTorch">
-  </a>
+  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/"><img src="https://github.com/gdmnl/Spectral-GNN-Benchmark/actions/workflows/docs.yaml/badge.svg" alt="Docs"></a>
+  <a href="https://github.com/gdmnl/Spectral-GNN-Benchmark?tab=MIT-1-ov-file"><img src="https://img.shields.io/github/license/gdmnl/Spectral-GNN-Benchmark" alt="License"></a>
+  <a href="https://github.com/gdmnl/Spectral-GNN-Benchmark/releases/latest"><img src="https://img.shields.io/github/v/release/gdmnl/Spectral-GNN-Benchmark?include_prereleases" alt="Contrib"></a>
+  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/_tutorial/installation.html"><img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fgdmnl%2FSpectral-GNN-Benchmark%2Fmain%2Fpyproject.toml&logo=python&label=Python" alt="Python"></a>
+  <a href="https://gdmnl.github.io/Spectral-GNN-Benchmark/_tutorial/installation.html"><img src="https://img.shields.io/badge/PyTorch->=2.0-FF6F00?logo=pytorch" alt="PyTorch"></a>
 </div>
 
 `pyg_spectral` is a [PyTorch Geometric](https://pyg.org)-based framework for analyzing, implementing, and benchmarking spectral GNNs with effectiveness and efficiency evaluations. Our paper is available on [arXiv](https://arxiv.org/abs/2406.09675).

diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
@@ -90,15 +90,15 @@ em.sig-param span.n:nth-child(4),
 em.sig-param span.n:nth-child(4) a,
 .sig-return {
   font-weight: normal;
-  font-style: normal;
+  font-style: italic;
 }
 em.sig-param span.default_value {
   font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
   font-style: normal;
 }
 
 /* Function Details */
-html.writer-html5 .rst-content dl.simple {
+/* html.writer-html5 .rst-content dl.simple {
   display: inherit;
 }
 html.writer-html5 .rst-content dl.simple dt,
@@ -112,10 +112,11 @@ html.writer-html5 .rst-content dl.simple dt {
   border: inherit !important;
   background: none !important;
   color: inherit !important;
-}
+} */
 /* Fix property layout */
 dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property {
   display: inline !important;
+  padding-right: 0 !important;
 }
 
 /* Tables */
@@ -165,9 +166,20 @@ div.highlight,
   border: none;
   background: rgba(27,31,35,.05);
   border-radius: 6px;
-}
-.rst-content code.xref {
   overflow-wrap: break-word;
+  padding: .2em .4em;
+}
+.rst-content em code.xref,
+.rst-content .sphinx_autodoc_typehints-type code.xref {
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: normal;
+  font-style: italic;
+  border: inherit;
+  background: inherit;
+  border-radius: inherit;
+  padding: inherit;
+  color: inherit;
 }
 div.highlight {
   background: linear-gradient(to bottom right, rgb(242,242,242), rgb(236,236,236));
@@ -209,9 +221,6 @@ div.highlight div.mac-header span.copy:hover {
 div.highlight div.mac-header span.copy:active {
   color: rgb(30,124,221);
 }
-.rst-content code.xref {
-  padding: .2em .4em;
-}
 .rst-content pre.literal-block,
 .rst-content div[class^="highlight"] {
   border: none;
@@ -338,7 +347,8 @@ span.inline-logo.empty {
   margin-right: -4px;
 }
 span.inline-logo.empty:before {
-  content: "\200b"; // unicode zero width space character
+  content: "\200b";
+  /* unicode zero width space character */
 }
 @-moz-document url-prefix() {
 span.inline-logo {
@@ -482,3 +492,17 @@ h1 span.pyg-mono {
 .nbsphinx-gallery > a:hover div:last-child {
   background: rgb(212,212,212);
 }
+
+button.copybtn {
+  opacity: 1;
+  background-color: inherit;
+  border: none;
+}
+
+.highlight button.copybtn:hover {
+  background-color: rgba(200,200,200,0.5);
+}
+
+.o-tooltip--left:hover:after {
+  opacity: 0;
+}
diff --git a/docs/source/_tutorial/installation.rst b/docs/source/_tutorial/installation.rst
@@ -1,7 +1,7 @@
 Installation
 ----------------------------------------
 
-This package can be easily installed by running `pip <https://pip.pypa.io/en/stable/>`_ at package root path:
+This package can be easily installed by running `pip <https://pip.pypa.io/en/stable/>`__ at package root path:
 
 .. code-block:: bash
 
@@ -10,16 +10,16 @@ This package can be easily installed by running `pip <https://pip.pypa.io/en/sta
 
 The installation script already covers the following core dependencies:
 
-- `PyTorch <https://github.com/pytorch/pytorch>`_ (``>=2.0`` [1]_)
-- `PyTorch Geometric <https://github.com/pyg-team/pytorch_geometric>`_ (``>=2.5.3``)
-- `TorchMetrics <https://github.com/Lightning-AI/torchmetrics>`_ (``>=1.0``): only required for ``benchmark/`` experiments.
-- `Optuna <https://github.com/optuna/optuna>`_ (``>=3.4``): only required for hyperparameter search in ``benchmark/`` experiments.
+- `PyTorch <https://github.com/pytorch/pytorch>`__ (``>=2.0`` [1]_)
+- `PyTorch Geometric <https://github.com/pyg-team/pytorch_geometric>`__ (``>=2.5.3``)
+- `TorchMetrics <https://github.com/Lightning-AI/torchmetrics>`__ (``>=1.0``): only required for ``benchmark/`` experiments.
+- `Optuna <https://github.com/optuna/optuna>`__ (``>=3.4``): only required for hyperparameter search in ``benchmark/`` experiments.
 
 
 Advanced Options
 ++++++++++++++++++++++++
 
-Installations can be specified by pip options. The following options can also be combined on demand.
+Installation can be specified by pip options. The following options can also be combined on demand.
 
 Only ``pyg_spectral`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -63,4 +63,4 @@ C++ Backend
 
    export PSFLAG_CPP=1; pip install -e .[cpp]
 
-.. [1] Please refer to the `official guide <https://pytorch.org/get-started/locally/>`_ if a specific CUDA version is required for PyTorch.
+.. [1] Please refer to the `official guide <https://pytorch.org/get-started/locally/>`__ if a specific CUDA version is required for PyTorch.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -4,43 +4,84 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os.path as osp
 import sys
+from datetime import datetime
+import importlib
+import inspect
 # import pyg_sphinx_theme
 
+import pyg_spectral
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'pyg_spectral'
-copyright = '2024, NTU'
-author = 'Ningyi Liao'
-release = '1.0.0'
-
 proot = osp.abspath(osp.dirname(osp.dirname(osp.dirname((osp.realpath(__file__))))))
 sys.path.insert(0, proot)
 sys.path.insert(1, osp.join(proot, 'benchmark'))
 # sys.path.append(osp.join(osp.dirname(pyg_sphinx_theme.__file__), 'extension'))
 
+project = 'pyg_spectral'
+author = 'Ningyi Liao'
+copyright = f'{datetime.now().year}, NTU'
+version = pyg_spectral.__version__
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+templates_path = ['_templates']
+exclude_patterns = []
+source_suffix = ['.rst', '.md']
+
+add_module_names = False
+show_authors = False
+modindex_common_prefix = ['pyg_spectral.', 'benchmark.']
 
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode',
+    'sphinx.ext.linkcode',
     'nbsphinx',
     'myst_parser',
+    'sphinx_copybutton',
+    'sphinx_autodoc_typehints',
     # 'pyg',
 ]
 
+autodoc_member_order = 'bysource'
+autodoc_typehints = 'signature'
 autosummary_generate = True
 autosummary_imported_members = True
-templates_path = ['_templates']
-exclude_patterns = []
+copybutton_exclude = '.linenos, .gp'
 
-source_suffix = ['.rst', '.md']
+napoleon_numpy_docstring = False
+napoleon_custom_sections = [
+    ('Returns', 'params_style'),
+]
+napoleon_use_rtype = False
+napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_preprocess_types = True
+autodoc_type_aliases = {
+    "Tensor": ":external:class:`Tensor <torch.Tensor>`",
+    # "SparseTensor": ":class:`torch_sparse.SparseTensor`",
+    "pyg": "torch_geometric",
+}
+napoleon_type_aliases = autodoc_type_aliases
+always_use_bars_union = True
+typehints_defaults = 'comma'
+typehints_document_rtype = False
+typehints_use_signature = True
+typehints_use_signature_return = True
+
+latex_elements = {
+    'preamble': r'''
+\usepackage[utf8]{inputenc}
+\usepackage{charter}
+\usepackage[defaultsans]{lato}
+''',
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -50,11 +91,11 @@
     "logo_only": False,
     "display_version": True,
     "navigation_depth": 2,
+    "prev_next_buttons_location": "both",
 }
 html_static_path = ['_static']
 
 html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
-add_module_names = True
 
 html_context = {
     "display_github": True,
@@ -72,7 +113,68 @@
 }
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/', None),
+    'python': ('https://docs.python.org/3/', None),
     'torch': ('https://pytorch.org/docs/master', None),
     'pyg': ('https://pytorch-geometric.readthedocs.io/en/latest/', None),
+    'torch_geometric': ('https://pytorch-geometric.readthedocs.io/en/latest/', None),
 }
+
+code_url = f"https://github.com/gdmnl/Spectral-GNN-Benchmark/blob/main"
+
+def linkcode_resolve(domain, info):
+    def _resolve_python(info):
+        # ref: https://github.com/scikit-learn/scikit-learn/blob/f7026e575a494b47b50557932b5c3ce0688fdc72/doc/sphinxext/github_link.py
+        def _inspect_macro(obj, func):
+            try:
+                res = func(obj)
+            except Exception:
+                res = None
+            if not res:
+                try:
+                    res = func(sys.modules[obj.__module__])
+                except Exception:
+                    res = None
+            if not res:
+                for f in ['fget', 'fset', 'fdel']:
+                    try:
+                        res = func(getattr(obj, f))
+                        break
+                    except Exception:
+                        continue
+            return res
+
+        mod = importlib.import_module(info["module"])
+        is_parent = False
+        if "." in info["fullname"]:
+            objname, attrname = info["fullname"].split(".")
+            obj = getattr(mod, objname)
+            try:
+                obj = getattr(obj, attrname)
+            except AttributeError:
+                # object is a class attribute
+                is_parent = True
+        else:
+            obj = getattr(mod, info["fullname"])
+        obj = inspect.unwrap(obj)
+
+        file = _inspect_macro(obj, inspect.getsourcefile)
+        if not file:
+            return
+        file = osp.relpath(file, proot)
+
+        lines = _inspect_macro(obj, inspect.getsourcelines)
+        if is_parent or not lines:
+            return f"{code_url}/{file}"
+        start, end = lines[1], lines[1] + len(lines[0]) - 1
+        return f"{code_url}/{file}#L{start}-L{end}"
+
+    if domain in ["py"]:
+        if not info.get("module") or not info.get("fullname"):
+            return None
+        return _resolve_python(info)
+    elif domain in ["c", "cpp"]:
+        if not info.get("names"):
+            return None
+        # TODO: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
+        pass
+    return None