DOC: Add version to documentation

.gitignore

@@ -60,6 +60,10 @@ tests/result_images/
 notes.txt
 examples/.ipynb_checkpoints
 
+# plotnine developing
+.ipynb_checkpoints/
+*.ipynb
+
 # Translations
 *.mo
 *.pot
@@ -86,11 +90,13 @@ benchmarks
 # version file generated by setuptools-scm
 plotnine/_version.py
 
+
 # Documentation
-qdoc/plotnine-examples
+qdoc/plotnine_examples/
 qdoc/reference/
 qdoc/_site/
 qdoc/.quarto/
 qdoc/gallery/thumbnails
 qdoc/objects.json
 qdoc/.luarc.json
+qdoc/_environment

plotnine/animation.py

@@ -31,7 +31,7 @@ class PlotnineAnimation(ArtistAnimation):
     plots : iterable
         ggplot objects that make up the the frames of the animation
     interval : number, optional
-       Delay between frames in milliseconds. Defaults to 200.
+        Delay between frames in milliseconds. Defaults to 200.
     repeat_delay : number, optional
         If the animation in repeated, adds a delay in milliseconds
         before repeating the animation. Defaults to `None`.

plotnine/doctools.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import re
 import typing
 from functools import lru_cache
@@ -146,6 +147,7 @@
 }
 
 PARAM_PATTERN = re.compile(r"\s*" r"([_A-Za-z]\w*)" r"\s:\s")
+GENERATING_QUARTODOC = os.environ.get("GENERATING_QUARTODOC")
 
 
 def dict_to_table(header: tuple[str, str], contents: dict[str, str]) -> str:
@@ -172,12 +174,9 @@ def dict_to_table(header: tuple[str, str], contents: dict[str, str]) -> str:
     fill      :py:`None`
     ========= =========
     """
-
-    import os
-
     from tabulate import tabulate
 
-    if os.environ.get("DOC_GENERATION"):
+    if GENERATING_QUARTODOC:
         return tabulate(
             list(contents.items()), headers=header, tablefmt="unsafehtml"
         )

qdoc/Makefile

@@ -3,7 +3,7 @@ setup:
 	git clone https://github.com/has2k1/plotnine-examples.git
 
 render:
-	DOC_GENERATION=1 python -m quartodoc build
+	GENERATING_QUARTODOC=1 python -m quartodoc build
 	quarto render
 
 doc: render

qdoc/_config.py

@@ -0,0 +1,46 @@
+import re
+import shutil
+from importlib.metadata import version as get_version
+from importlib.resources import files as _files
+from pathlib import Path
+
+DOC_DIR = Path(__file__).parent
+
+# The environment file holds the version
+ENV_TPL = """\
+VERSION={version}
+"""
+
+
+def generate_environment_file():
+    """
+    Generate _enviroment file in the quartodoc project directory
+    """
+    version = get_version("plotnine")
+
+    # The scm-version scheme adds .date suffix to the version
+    # if the repo is dirty. For better look while developing,
+    # we remove it.
+    dirty_pattern = re.compile(r"\.d\d{8}$")
+    if dirty_pattern.search(version):
+        version = dirty_pattern.sub("", version)
+
+    env_filepath = DOC_DIR / "_environment"
+    contents = ENV_TPL.format(version=version)
+    env_filepath.write_text(contents)
+
+
+def link_to_examples():
+    """
+    Copy the plotnine_examples package root
+    """
+    dest = DOC_DIR / "plotnine_examples"
+    if dest.is_dir() and not dest.is_symlink():
+        shutil.rmtree(dest)
+    src = _files("plotnine_examples")
+    shutil.copytree(src, dest)  # type: ignore
+
+
+if __name__ == "__main__":
+    generate_environment_file()
+    link_to_examples()

qdoc/_quarto.yml

@@ -1,5 +1,7 @@
 project:
   type: website
+  pre-render: _config.py
+  output-dir: _site
   resources:
     - objects.json
   render:
@@ -34,7 +36,8 @@ interlinks:
       url: https://patsy.readthedocs.io/en/stable
 
 website:
-  title: Plotnine
+  title: "plotnine {{< env VERSION >}}"
+  page-navigation: true
   navbar:
     left:
       - file: gallery/index.qmd

qdoc/_renderer.py

@@ -13,10 +13,10 @@
 from quartodoc.renderers.base import convert_rst_link_to_md
 from tabulate import tabulate
 
-P_ROOT = Path(__file__).parent
-EXAMPLES_FOLDER = P_ROOT / "plotnine-examples/plotnine_examples"
+DOC_DIR = Path(__file__).parent
+EXAMPLES_DIR = DOC_DIR / "plotnine_examples"
 
-DOCSTRING_TMPL = """\
+DOCSTRING_TPL = """\
 {rendered}
 
 Examples
@@ -47,11 +47,11 @@ def render(self, el: dc.Object | dc.Alias):  # type: ignore # noqa: F811
 
         converted = convert_rst_link_to_md(rendered)
 
-        p_example = EXAMPLES_FOLDER / "examples" / (el.name + ".ipynb")
-        if p_example.exists():
-            rel_path = Path("..") / p_example.relative_to(P_ROOT)
-            example = f"{{{{< embed {rel_path} echo=true >}}}}"
-            return DOCSTRING_TMPL.format(rendered=converted, examples=example)
+        example_path = EXAMPLES_DIR / "examples" / (el.name + ".ipynb")
+        if example_path.exists():
+            rel_path = Path("..") / example_path.relative_to(DOC_DIR)
+            example = "{{< embed" f" {rel_path} " "echo=true >}}"
+            return DOCSTRING_TPL.format(rendered=converted, examples=example)
 
         return converted
 

qdoc/gallery/index.qmd

@@ -17,7 +17,8 @@ from pathlib import Path
 
 THUMBNAIL_SIZE = (294, 210)
 
-p_examples = Path("../plotnine-examples/plotnine_examples/examples")
+DOC_DIR = Path(".").resolve().parent
+p_examples = DOC_DIR / "plotnine_examples/examples"
 
 # note that plotnine site uses essentially /_images
 p_thumbnails = Path("thumbnails")
@@ -47,10 +48,10 @@ def extract_image(fname):
             title = find_first_title(reversed(nb["cells"][:ii])) or ""
             # currently, I think the gallery only gets the first plot
             cell_plots.append((title, out_plots[0]))
-    
+
     if cell_plots:
         return cell_plots
-    
+
     raise Exception("No image found")
 
 
@@ -73,7 +74,7 @@ def create_thumbnail(output, dst_thumb: str, thumbnail_size: tuple[int, int]):
     # thumbnail_size = (294, 210)
     thumb_size = thumbnail_size[0] * 2, thumbnail_size[1] * 2
 
-    # I'm not sure if this just 
+    # I'm not sure if this just
     img.thumbnail(thumb_size)
 
     p_dst = Path(f"{dst_thumb}.png")
@@ -102,7 +103,7 @@ def gallery_entry(src_thumbnail: str, href: str, title: str):
 </a>
 </div>
 """
-    
+
 entries = []
 
 for notebook_name, path in gallery_notebooks.items():
@@ -122,8 +123,8 @@ for notebook_name, path in gallery_notebooks.items():
 
 ```{python}
 #| output: asis
-#| echo: false 
+#| echo: false
 print(gallery(entries))
 ```
 
-:::
+:::