Revamp documentation (#25)

* feat: create new documentation skeleton

* refactor: adjust style

* feat: generate table reference from TSV files

* refactor: migrate content of original README to new docs

* lint: apply formatting

* feat: use notebooks in tutorials

* feat: add api usage examples to api.md

* feat: add dataset.md

* chore: update dataset.md

* refactor: restructure dataset tutorial

* refactor: refactor dataset tutorial and reference

* refactor: remove temporary code

* fix: adapt CI to new documentation build

* lint: ruff format

* lint: fix newline at end of file

* fix: typo

* fix: adopt Sphinx table style

* fix: use correct plinder.__version__

* chore: comment out plinder API card

* chore: update dataset.md

* chore: fix local merge conflict

* minor edits to dataset tutorial

* fix: temporary fix for card layout

---------

Co-authored-by: yusuf1759 <mr.adeshina.yusuf@gmail.com>
Co-authored-by: Thomas Duignan <thomas.j.duignan@gmail.com>
Co-authored-by: OleinikovasV <v.oleinikovas@gmail.com>

Author: 4 people

.github/workflows/docs.yaml

@@ -32,18 +32,21 @@ jobs:
           cache-downloads: true
           cache-environment: true
           post-cleanup: all
+      - name: Get version bump
+        id: get-tag
+        run: echo "bump=$(python flows/docker.py bump)" >> $GITHUB_OUTPUT
       - name: Build docs
         shell: bash -el {0}
         id: build
         run: |
           which python
           python -m pip install six
           python -m pip install '.[docs]'
-          pushd docs && bash build.sh && popd
+          sphinx-build docs build/docs
       - name: Upload build artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/build/html/
+          path: build/docs
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -86,11 +86,9 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
+# Generated files in Sphinx documentation
 docs/_build/
-docs/source/_static
-docs/source/plinder*
-docs/source/modules*
+docs/table.html
 
 # PyBuilder
 .pybuilder/

README.md

@@ -44,8 +44,11 @@ We recommend the [miniforge](https://github.com/conda-forge/miniforge) environme
 
 **NOTE**: We currently only support a Linux environment. `plinder`
 uses `openstructure` for some of its functionality and is available
-from the `aivant` conda channel using `conda install aivant::openstructure`, but it is only built targeting Linux architectures.
-For MacOS users, please see the relevant [docker](#package-publishing) resources below.
+from the `aivant` conda channel using `conda install aivant::openstructure`,
+but it is only built targeting Linux architectures. We also depend on
+`networkit>=11.0` which as of the time of writing does not build from source
+cleanly on MacOS. For MacOS users, please see the relevant
+[docker](#package-publishing) resources below.
 
 ## Install plinder
 

docs/Makefile

@@ -0,0 +1,9 @@
+---
+sd_hide_title: true
+---
+
+# Python API
+
+## API reference
+
+**Coming soon**

docs/api.md

@@ -0,0 +1,16 @@
+# Citation
+
+If you find PLINDER useful, please cite:
+
+> Janani Durairaj, Yusuf Adeshina, Zhonglin Cao, Xuejin Zhang, Vladas Oleinikovas,
+Thomas Duignan, Zachary McClure, Xavier Robin, Gabriel Studer, Daniel Kovtun,
+Emanuele Rossi, Guoqing Zhou, Srimukh Veccham, Clemens Isert, Yuxing Peng,
+Prabindh Sundareson, Mehmet Akdel, Gabriele Corso, Hannes Stärk, Gerardo Tauriello,
+Zachary Carpenter, Michael Bronstein, Emine Kucukbenli, Torsten Schwede, Luca Naef,\
+"PLINDER: The protein-ligand interactions dataset and evaluation resource",\
+_bioRxiv_
+July 2024;
+doi: [10.1101/2024.07.17.603955](https://doi.org/10.1101/2024.07.17.603955)
+
+You may also get a useful summary from the
+[ICML'24 ML4LMS poster submission](https://openreview.net/forum?id=7UvbaTrNbP).

docs/build.sh

@@ -0,0 +1,136 @@
+import sys
+from pathlib import Path
+
+import plinder
+
+DOC_PATH = Path(__file__).parent
+PACKAGE_PATH = DOC_PATH.parent / "src"
+COLUMN_REFERENCE_PATH = DOC_PATH.parent / "column_descriptions"
+
+# Include documentation in PYTHONPATH
+# in order to import modules for API doc generation etc.
+sys.path.insert(0, str(DOC_PATH))
+import tablegen
+
+# Pregeneration of files
+tablegen.generate_table(COLUMN_REFERENCE_PATH, DOC_PATH / "table.html")
+
+#### Source code link ###
+
+# linkcode_resolve = viewcode.linkcode_resolve
+
+#### General ####
+
+extensions = [
+    "jupyter_sphinx",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.mathjax",
+    # "sphinx.ext.linkcode",
+    "sphinx.ext.todo",
+    "sphinx_design",
+    "sphinx_copybutton",
+    "numpydoc",
+    "myst_nb",
+]
+
+nb_custom_formats = {".ipynb": ["jupytext.reads", {"fmt": "ipynb"}]}
+nb_execution_timeout = 720
+nb_kernel_rgx_aliases = {"plinder.*": "python3"}
+myst_enable_extensions = [
+    "amsmath",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+myst_url_schemes = ("http", "https", "mailto")
+
+templates_path = ["templates"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
+master_doc = "index"
+
+project = "PLINDER"
+copyright = "2024, PLINDER Development Team"
+author = "PLINDER Development Team"
+version = plinder.__version__
+release = plinder.__version__
+
+pygments_style = "sphinx"
+
+#### HTML ####
+
+html_theme = "pydata_sphinx_theme"
+
+html_static_path = ["static"]
+html_css_files = [
+    "plinder.css",
+    # For rendering the column descriptions table
+    "https://cdn.datatables.net/2.1.3/css/dataTables.dataTables.css",
+    # Get fonts from Google Fonts CDN
+    "https://fonts.googleapis.com/css2"
+    "?family=Geologica:wght@100..900"
+    "&family=Montserrat:ital,wght@0,100..900;1,100..900"
+    "&display=swap",
+]
+html_js_files = [
+    # For rendering the column descriptions table
+    "https://code.jquery.com/jquery-3.7.1.js",
+    "https://cdn.datatables.net/2.1.3/js/dataTables.js",
+]
+html_title = "PLINDER"
+html_logo = "static/assets/general/plinder_logo.png"
+html_favicon = "static/assets/general/plinder_icon.png"
+html_baseurl = "https://plinder-org.github.io/plinder/"
+html_theme_options = {
+    "header_links_before_dropdown": 7,
+    "pygments_light_style": "friendly",
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/plinder-org/plinder/",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Article",
+            "url": "https://www.biorxiv.org/content/10.1101/2024.07.17.603955v3",
+            "icon": "fa-solid fa-file-lines",
+            "type": "fontawesome",
+        },
+    ],
+    "use_edit_page_button": True,
+    "show_prev_next": False,
+    "show_toc_level": 2,
+}
+html_sidebars = {
+    # No primary sidebar for these pages
+    "dataset": [],
+}
+html_context = {
+    "github_user": "plinder-org",
+    "github_repo": "plinder",
+    "github_version": "main",
+    "doc_path": "doc",
+}
+
+
+#### App setup ####
+
+
+# def setup(app):
+#    app.connect("autodoc-skip-member", apidoc.skip_nonrelevant)

docs/citation.md

@@ -0,0 +1,59 @@
+# Contributor guide
+
+The PLINDER project is a community effort, launched by the University of Basel,
+SIB Swiss Institute of Bioinformatics, VantAI, NVIDIA, MIT CSAIL, and will be regularly
+updated.
+We highly welcome contributions!
+
+## Development installation
+
+```console
+$ git clone git@github.com:plinder-org/plinder.git
+$ cd plinder
+$ mamba env create -f environment.yml
+$ mamba activate plinder
+$ pip install -e '.[dev]'
+```
+
+Please install pre-commit hooks (the same checks will run in CI):
+
+```console
+$ pre-commit install
+```
+
+## Test suite
+
+Test linting checks:
+
+```console
+$ tox -e lint
+```
+
+Run typing checks:
+
+```console
+$ tox -e type
+```
+
+Run the test suite:
+
+```console
+$ tox -e test
+```
+
+We lint with `ruff`.
+See `tox.ini` and `.pre-commit-config.yaml` for details.
+
+## Debugging
+
+In order to change log levels in `plinder`, please set:
+
+```console
+export PLINDER_LOG_LEVEL=10
+```
+
+:::{todo}
+- more details for each command
+- add detailed information on other `plinder` subpackages aprt from `core`
+- split into multiple documents
+:::