Setting up infrastructure for documentation and jupyterlite (#82)

.github/workflows/docs.yaml

@@ -21,7 +21,7 @@ on:
     - cron: '0 13 * * SUN'
 
 env:
-  PYTHON_VERSION: 3.9
+  PYTHON_VERSION: "3.9"
 
 jobs:
   build_docs:

.github/workflows/jupyterlite.yaml

@@ -21,7 +21,7 @@ on:
     - cron: '0 19 * * SUN'
 
 env:
-  PYTHON_VERSION: 3.10
+  PYTHON_VERSION: "3.10"
   NODE_VERSION: "18"
 
 jobs:

.gitignore

@@ -6,3 +6,15 @@ dist
 scratch
 holonote/_version.py
 annotations.db
+
+# docs
+builtdocs
+jupyter_execute
+doc/**/*.rst
+doc/**/*.ipynb
+
+# jupyterlite
+jupyterlite/
+!scripts/jupyterlite
+scripts/jupyterlite/.jupyterlite.doit.db
+scripts/jupyterlite/*.json

README.md

@@ -3,7 +3,7 @@
 The `holonote` library offers tools to create, edit and persist
 annotated regions for [HoloViews](https://holoviews.org/).
 
-![Annotation demo](https://github.com/holoviz/holonote/blob/main/examples/assets/demo.gif)
+![Annotation demo](https://assets.holoviz.org/holonote/demo.gif)
 
 An annotated region marks a region-of-interest that is overlaid on top
 of the visual representation of a HoloViews element. Such a region has a

doc/_static/css/custom.css

@@ -0,0 +1,79 @@
+:root[data-theme='light'],
+:root[data-theme='dark'] {
+    --pst-color-primary: rgb(47,47,47);
+    --pst-color-link: rgb(163,26,38);
+    --pst-color-link-hover: rgb(254,203,56);
+    --pst-color-surface: rgb(250, 250, 250);
+}
+
+/* Fix breadcrumb overlap https://github.com/holoviz/panel/issues/5199 */
+.header-article__inner .header-article-item {
+  height: unset;
+}
+
+/* Homepage Showcase */
+
+.showcase-table {
+  border-spacing: 15px;
+}
+
+.showcase-table td {
+  border: 0px;
+  vertical-align: top;
+}
+
+/* Homepage sponsors */
+
+.sd-card-body.sponsor-logo {
+  flex-grow: unset;
+  margin: auto;
+}
+
+.sponsor-logo img {
+  min-height: 80px;
+  object-fit: contain;
+}
+
+/* Tweaks for code cell rendering */
+
+.highlight {
+  border-radius: 4px;
+}
+
+html[data-theme='light'] .highlight {
+  background-color: #263238;
+  color: #f8f8f2;
+}
+
+pre[id^='codecell'] {
+  background-color: unset;
+  border: none;
+  border-radius: 0.5em;
+  color: #f8f8f2;
+  box-shadow: none;
+  padding: 1.5em;
+}
+
+div.highlight button.copybtn.o-tooltip--left:after {
+  background-color: #263235;
+  border: 1px solid gray;
+  border-radius: 4px;
+  padding: 5px;
+}
+
+button.copybtn {
+  background-color: #263238;
+}
+
+button.copybtn:hover {
+  background-color: #263238;
+  color: #f8f8f2;
+}
+
+.highlight button.copybtn:hover {
+  background: none;
+}
+
+.o-tooltip--left:after {
+  background: none;
+}

doc/_templates/jupyterlitelink.html

@@ -0,0 +1,8 @@
+{# Custom template to include a link to Panelite #}
+<div class="tocsection">
+{% if title and pagename != root_doc and (pagename.startswith("tutorial") or pagename.startswith("basics")) %}
+  <a href="{{ jupyterlite_endpoint + '/lab' + ('' if pagename.endswith('index') else '?path=' + pagename + '.ipynb') }}" target=”_blank”>
+    <img src="{{ pathto('_static/assets/jupyterlite.svg', 1) }}" alt="launch jupyterlite"></img>
+  </a>
+{% endif %}
+</div>

doc/basics/index.md

@@ -0,0 +1,14 @@
+# Basics
+
+Will give a short introduction to the basics of holonote.
+
+```{toctree}
+:titlesonly:
+:hidden:
+:maxdepth: 1
+
+Basics
+Basics_2D
+MultiPlot
+styling
+```

doc/conf.py

@@ -0,0 +1,146 @@
+import os
+from pathlib import Path
+
+import param
+from nbsite.shared_conf import *  # noqa: F403
+
+import holonote as hn
+
+param.parameterized.docstring_signature = False
+param.parameterized.docstring_describe_params = False
+
+
+project = "HoloNote"
+authors = "HoloNote contributors"
+copyright_years["start_year"] = "2023"
+copyright = copyright_fmt.format(**copyright_years)
+description = "Tools to create, edit and persist annotated regions for HoloViews"
+version = release = base_version(hn.__version__)
+is_dev = any(ext in version for ext in ("a", "b", "rc"))
+
+HOLONOTE_ROOT = Path(hn.__file__).parents[1]
+# Remove database files if they exist
+for db in (HOLONOTE_ROOT / "examples").rglob("*.db"):
+    db.unlink()
+
+
+# For the interactivity warning box created by nbsite to point to the right
+# git tag instead of the default i.e. main.
+os.environ["BRANCH"] = f"v{release}"
+
+html_static_path += ["_static"]
+
+html_css_files += ["css/custom.css"]
+
+html_theme = "pydata_sphinx_theme"
+# html_favicon = "_static/icons/favicon.ico"
+
+html_theme_options = {
+    # "logo": {
+    #     "image_light": "_static/logo_horizontal_light_theme.png",
+    #     "image_dark": "_static/logo_horizontal_dark_theme.png",
+    # },
+    "github_url": "https://github.com/holoviz/holonote",
+    "icon_links": [
+        {
+            "name": "Discourse",
+            "url": "https://discourse.holoviz.org/",
+            "icon": "fa-brands fa-discourse",
+        },
+        {
+            "name": "Discord",
+            "url": "https://discord.gg/UXdtYyGVQX",
+            "icon": "fa-brands fa-discord",
+        },
+    ],
+    "pygment_light_style": "material",
+    "pygment_dark_style": "material",
+    "header_links_before_dropdown": 5,
+    "secondary_sidebar_items": [
+        "github-stars-button",
+        "jupyterlitelink",
+        "page-toc",
+    ],
+}
+
+extensions += ["sphinx.ext.napoleon", "nbsite.gallery"]
+napoleon_numpy_docstring = True
+
+myst_enable_extensions = ["colon_fence", "deflist"]
+
+jupyterlite_url = "https://holoviz-dev.github.io/holonote-jupyterlite"
+
+nbsite_gallery_conf = {
+    "github_org": "holoviz",
+    "github_project": "holonote",
+    "jupyterlite_url": jupyterlite_url,
+    "galleries": {},
+}
+
+templates_path += ["_templates"]
+
+html_context.update(
+    {
+        "last_release": f"v{release}",
+        "github_user": "holoviz",
+        "github_repo": "holonote",
+        "default_mode": "light",
+        "jupyterlite_endpoint": jupyterlite_url,
+    }
+)
+
+nbbuild_patterns_to_take_along = ["simple.html", "*.json", "json_*"]
+
+# Override the Sphinx default title that appends `documentation`
+html_title = f"{project} v{version}"
+
+
+# Patching GridItemCardDirective to be able to substitute the domain name
+# in the link option.
+# from sphinx_design.cards import CardDirective
+# from sphinx_design.grids import GridItemCardDirective
+
+# orig_grid_run = GridItemCardDirective.run
+
+
+# def patched_grid_run(self):
+#     app = self.state.document.settings.env.app
+#     existing_link = self.options.get("link")
+#     domain = getattr(app.config, "grid_item_link_domain", None)
+#     if self.has_content:
+#         self.content.replace("|gallery-endpoint|", domain)
+#     if existing_link and domain:
+#         new_link = existing_link.replace("|gallery-endpoint|", domain)
+#         self.options["link"] = new_link
+#     return list(orig_grid_run(self))
+
+
+# GridItemCardDirective.run = patched_grid_run
+
+# orig_card_run = CardDirective.run
+
+
+# def patched_card_run(self):
+#     app = self.state.document.settings.env.app
+#     existing_link = self.options.get("link")
+#     domain = getattr(app.config, "grid_item_link_domain", None)
+#     if existing_link and domain:
+#         new_link = existing_link.replace("|gallery-endpoint|", domain)
+#         self.options["link"] = new_link
+#     return orig_card_run(self)
+
+
+# CardDirective.run = patched_card_run
+
+
+def setup(app) -> None:
+    try:
+        from nbsite.paramdoc import param_formatter, param_skip
+
+        app.connect("autodoc-process-docstring", param_formatter)
+        app.connect("autodoc-skip-member", param_skip)
+    except ImportError:
+        print("no param_formatter (no param?)")
+
+    nbbuild.setup(app)
+    app.add_config_value("grid_item_link_domain", "", "html")