diff --git a/.gitignore b/.gitignore index 1f5867aa2..03830ea12 100644 --- a/.gitignore +++ b/.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 diff --git a/plotnine/animation.py b/plotnine/animation.py index 10552643f..73e17b3bf 100644 --- a/plotnine/animation.py +++ b/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`. diff --git a/plotnine/doctools.py b/plotnine/doctools.py index 0bf4be65f..2a0e71523 100644 --- a/plotnine/doctools.py +++ b/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" ) diff --git a/qdoc/Makefile b/qdoc/Makefile index c2d4e6f34..083765d03 100644 --- a/qdoc/Makefile +++ b/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 diff --git a/qdoc/_config.py b/qdoc/_config.py new file mode 100644 index 000000000..bf0f8b75d --- /dev/null +++ b/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() diff --git a/qdoc/_quarto.yml b/qdoc/_quarto.yml index eb861c45e..2689b7c34 100644 --- a/qdoc/_quarto.yml +++ b/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 diff --git a/qdoc/_renderer.py b/qdoc/_renderer.py index 0edfbc575..363456412 100644 --- a/qdoc/_renderer.py +++ b/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 diff --git a/qdoc/gallery/index.qmd b/qdoc/gallery/index.qmd index 27a52fa95..432589cf7 100644 --- a/qdoc/gallery/index.qmd +++ b/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): """ - + 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)) ``` -::: \ No newline at end of file +:::