Remove unused dependencies, adapt script for copying notebooks, updat…

…e configuration
aai-institute · Jun 29, 2023 · 490e1d8 · 490e1d8
1 parent 341e966
commit 490e1d8
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 31 deletions.
diff --git a/docs/_ext/copy_notebooks.py → build_scripts/copy_notebooks.py b/docs/_ext/copy_notebooks.py → build_scripts/copy_notebooks.py
@@ -1,22 +1,26 @@
+import logging
 import os
 import shutil
 from pathlib import Path
 
-from sphinx.application import Sphinx
-from sphinx.config import Config
-from sphinx.util import logging
+import mkdocs.plugins
 
 logger = logging.getLogger(__name__)
 
+root_dir = Path(__file__).parent.parent
+docs_examples_dir = root_dir / "docs" / "examples"
+notebooks_dir = root_dir / "notebooks"
 
-def copy_notebooks(app: Sphinx, config: Config) -> None:
-    logger.info("Copying notebooks to examples directory")
-    root_dir = Path(app.confdir).parent
-    notebooks_dir = root_dir / "notebooks"
-    docs_examples_dir = root_dir / "docs" / "examples"
+
+@mkdocs.plugins.event_priority(100)
+def on_pre_build(config):
+    logger.info("Temporarily copying notebooks to examples directory")
+    docs_examples_dir.mkdir(parents=True, exist_ok=True)
     notebook_filepaths = list(notebooks_dir.glob("*.ipynb"))
+
     for notebook in notebook_filepaths:
         target_filepath = docs_examples_dir / notebook.name
+
         try:
             if os.path.getmtime(notebook) <= os.path.getmtime(target_filepath):
                 logger.info(
@@ -28,9 +32,13 @@ def copy_notebooks(app: Sphinx, config: Config) -> None:
         logger.info(
             f"Copying '{os.fspath(notebook)}' to '{os.fspath(target_filepath)}'"
         )
-        shutil.copyfile(src=notebook, dst=target_filepath)
+        shutil.copy2(src=notebook, dst=target_filepath)
+
     logger.info("Finished copying notebooks to examples directory")
 
 
-def setup(app):
-    app.connect("config-inited", copy_notebooks)
+@mkdocs.plugins.event_priority(-100)
+def on_shutdown():
+    logger.info("Removing temporary examples directory")
+    for notebook_file in docs_examples_dir.glob("*.ipynb"):
+        notebook_file.unlink()
diff --git a/docs/10-getting-started.md b/docs/10-getting-started.md
@@ -29,7 +29,7 @@ introduction and survey of the field, we refer to **the upcoming review** at the
 If you are somewhat familiar with the concepts of data valuation, you can start
 by browsing our worked-out examples illustrating pyDVL's capabilities either:
 
-- [In this documentation][examples/].
+- [[examples]].
 - Using [binder](https://mybinder.org/>) notebooks, deployed from each
   example's page.
 - Locally, by starting a jupyter server at the root of the project. You will

diff --git a/docs/css/extra.css b/docs/css/extra.css
@@ -71,3 +71,8 @@ a.autorefs-external:hover::after {
 .md-header__button.md-logo img, .md-header__button.md-logo svg {
   height: 1.9rem;
 }
+
+/* Prevent selection of >>>, ... and output in Python code blocks */
+.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
+    user-select: none;
+}
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -0,0 +1,10 @@
+---
+title: Examples
+alias: 
+    name: examples
+    text: Examples
+---
+
+This section contains worked-out examples illustrating pyDVL's capabilities.
+
+Use the navigation bar on the left to go through them.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -7,13 +7,23 @@ copyright: "Copyright &copy; AppliedAI Institute gGmbH"
 watch:
   - src/pydvl
 
+hooks:
+  - build_scripts/copy_notebooks.py
+
 plugins:
   - autorefs
   - search
   - section-index
   - alias:
       use_relative_link: true
       verbose: true
+  - gen-files:
+      scripts:
+        - build_scripts/generate_api_docs.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocs-jupyter:
+      include: ["docs/examples/*.ipynb"]
   - mkdocstrings:
       enable_inventory: true
       handlers:
@@ -29,27 +39,20 @@ plugins:
             line_length: 80
             show_bases: true
             members_order: source
-            # separate_signature: true
+            show_submodules: false
             show_signature_annotations: false
             signature_crossrefs: true
-            # show_if_no_docstring: true
             merge_init_into_class: true
             docstring_options:
               ignore_init_summary: true
-            # filters: [] # include all members
-  - gen-files:
-      scripts:
-        - build_scripts/generate_api_docs.py
-  - literate-nav:
-      nav_file: SUMMARY.md
   - bibtex:
       bib_file: "docs/assets/pydvl.bib"
       csl_file: "docs/assets/elsevier-harvard.csl"
       cite_inline: true
-  #- git-revision-date-localized:
-  #    enable_creation_date: true
-  #    type: iso_date
-  #    fallback_to_build_date: true
+  - git-revision-date-localized:
+      enable_creation_date: true
+      type: iso_date
+      fallback_to_build_date: true
 
 theme:
   name: material
@@ -62,12 +65,11 @@ theme:
     - search.suggest
     - search.highlight
     - toc.follow
-    # - navigation.tabs
-    # - navigation.tabs.sticky
+    - navigation.top
     - navigation.instant
     - navigation.sections
+    - navigation.path
     - navigation.tracking
-    # - navigation.top
     - navigation.footer
     - content.code.copy
     - content.code.annotate

diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -1,15 +1,13 @@
 mkdocs==1.4.2
 mkdocs-material
 mkdocstrings[python]>=0.18
+mkdocs-jupyter
 mkdocs-alias-plugin>=0.6.0
 mkdocs-autorefs
 mkdocs-gen-files
 mkdocs-literate-nav
 mkdocs-section-index
 mkdocs-bibtex
 neoteroi-mkdocs  # Needed for card grid on home page
-mkdocs-gallery
-mkdocs-nbconvert
 mkdocs-git-revision-date-localized-plugin
-pypandoc
-pypandoc_binary
+pypandoc_binary