Develop (#28)

* Feature/print friendly pages (#21) * Correct print formatting * Update docs and version number * Update docs * Update roadmap * Update release notes * Update release notes formatting * Feature/output to pdf (#25) * Move Jinja template to resources directory * Add weasyprint dependency * Implement and test PDF creation * Update docs * Fix image scaling * Extract image resizing to external function * Revert back to current API for scaling * Omit display, getters, setters from coverage * Update lock file * Feature/inline content dependencies (#26) * Refactor content dependency handling * Allow inline dependencies * Add user options for offline mode * Feature/render plots as svg (#27) * Add svg export for plots * Update docs * Update iris example
domvwt · May 3, 2021 · 52ea7ac · 52ea7ac
1 parent c75fecf
commit 52ea7ac
Show file tree

Hide file tree

Showing 26 changed files with 28,656 additions and 370 deletions.
diff --git a/.coveragerc b/.coveragerc
@@ -8,6 +8,18 @@ exclude_lines =
     pragma: no cover
     raise NotImplementedError
     if __name__ == .__main__.:
+    def __repr__
+    def _repr_html_
+    def __str__
+    def display
+    return self._
+    def set_
+    def _render_title
+    def _parent_class
+    def _child_class
+    if TYPE_CHECKING
+    if kwargs.get("pdf_mode"):
+    if output_format == "svg":
 ignore_errors = True
 omit =
     tests/*
diff --git a/README.md b/README.md
@@ -6,23 +6,44 @@ esparto
 [![codecov](https://codecov.io/gh/domvwt/esparto/branch/main/graph/badge.svg?token=35J8NZCUYC)](https://codecov.io/gh/domvwt/esparto)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=domvwt_esparto&metric=alert_status)](https://sonarcloud.io/dashboard?id=domvwt_esparto)
 
-Esparto is a super minimal frontend web framework written in Python. Its primary use is for generating shareable single page documents
+Esparto is a simple HTML and PDF document generator for Python. Its primary use is for generating shareable single page reports
 with content from popular analytics and data science libraries.
 
-Full documentation and examples at [domvwt.github.io/esparto/](https://domvwt.github.io/esparto/).
+Full documentation and examples are available at [domvwt.github.io/esparto/](https://domvwt.github.io/esparto/).
+
+## Overview
+The library features a streamlined API that defines pages in terms of
+sections, rows, and columns; and an intelligent wrapping system that automatically
+converts Python objects into content.
+
+We use the grid system and components from [Bootstrap](https://getbootstrap.com/) to ensure
+documents adapt to the viewing device and appear immediately familiar and accessible.
+No knowledge of Bootstrap or web development is required to use the library, however, as these
+details are conveniently abstracted.
+
+At publishing time, the completed document is passed to [Jinja2](https://palletsprojects.com/p/jinja/)
+and fed into an HTML template with all style details and dependencies captured inline.
+
+Esparto supports content rendering within Jupyter Notebooks, allowing users to interactively
+and iteratively build documents without disrupting their workflow.
+
+PDF conversion is provided by [Weasyprint](https://weasyprint.org/).
 
 ### Features
 * Lightweight API
 * No CSS or HTML required
 * Device responsive display
 * Self contained / inline dependencies
 * Jupyter Notebook support
+* Printer friendly formatting
+* PDF output
 * MIT License
 
 ### Supported Content
-* Markdown text
+* Markdown
 * Images
-* Matplotlib figures
 * Pandas DataFrames
-* Bokeh objects
-* Plotly figures
+* Plots from:
+    * Matplotlib
+    * Bokeh
+    * Plotly
diff --git a/docs/01-getting-started/quickstart.md b/docs/01-getting-started/quickstart.md
@@ -1,12 +1,22 @@
 Quickstart
 ==========
 
-The esparto library can be installed with pip:
+The esparto library can be installed with pip. Only the minimal package requirements will be installed by default:
 
 ```bash
 pip install esparto
 ```
 
+<br>
+
+For PDF output we will also require [weasyprint]("https://weasyprint.org/"), although
+this is optional:
+
+```bash
+pip install weasyprint
+```
+
+
 <br>
 
 Documents start with a Page object, to which user content can be added iteratively.
@@ -23,7 +33,7 @@ Your *content* goes **here!**
 """
 
 my_page += content_md
-my_page.save("esparto-quick.html")
+my_page.save_html("esparto-quick.html")
 ```
 <br>
 
@@ -47,7 +57,7 @@ Your *content* goes **here!**
 my_page += content_md
 my_page += "image.jpg"
 
-html = my_page.save("esparto-quick-image.html")
+my_page.save_html("esparto-quick-image.html")
 ```
 <br>
 
@@ -57,6 +67,14 @@ Esparto determines that the string points to a valid image and loads the file:
 
 <br>
 
+And for PDF output:
+
+```python
+my_page.save_pdf("esparto-quick-image.pdf")
+```
+
+<br>
+
 Please see the [examples page](../02-user-guide/examples.md) for more.
 
 <br>
diff --git a/docs/03-api-reference/content.md b/docs/03-api-reference/content.md
@@ -1,7 +1,7 @@
 # esparto._content
 
 !!! info
-    Content classes should be accessed from the module top level.
+    Content classes can be accessed from the module top level:
 
     ``` python
     import esparto as es

diff --git a/docs/03-api-reference/layout.md b/docs/03-api-reference/layout.md
@@ -1,7 +1,7 @@
 # esparto._layout
 
 !!! info
-    Layout classes should be accessed from the module top level.
+    Layout classes can be accessed from the module top level:
 
     ``` python
     import esparto as es

diff --git a/docs/03-api-reference/publish.md b/docs/03-api-reference/publish.md
@@ -1,24 +1,26 @@
 # esparto._publish
 
 !!! info
-    Publishing methods should be accessed via Layout classes.
+    Publishing methods should usually be accessed via Layout classes:
 
     ``` python
     import esparto as es
 
     # Create a new Page
     page = es.Page(title="My New Page")
 
-    # Render to Jupyter Notebook cell:
-    page.display()
-
     # Publish the document to an HTML file:
-    page.save()
+    page.save_html("my-page.html")
+
+    # Or as a PDF:
+    page.save_pdf("my-page.pdf")
 
     ```
 
-## ::: esparto._publish.publish
+### ::: esparto._publish.publish_html
+
+### ::: esparto._publish.publish_pdf
 
-## ::: esparto._publish.nb_display
+### ::: esparto._publish.nb_display
 
 <br>
diff --git a/docs/04-about/contributing.md b/docs/04-about/contributing.md
@@ -77,9 +77,8 @@ Ready to contribute? Here's how to set up esparto for local development.
 5.  When you're done making changes, check that your changes pass flake8
     and the tests, including testing other Python versions with tox:
 
-        $ flake8 esparto tests
-        $ python setup.py test or pytest
-        $ tox
+        $ make format lint mypy test
+        $ make test-all
 
     To get flake8 and tox, just pip install them into your virtualenv.
 
@@ -100,8 +99,8 @@ Before you submit a pull request, check that it meets these guidelines:
 2.  If the pull request adds functionality, the docs should be updated.
     Put your new functionality into a function with a docstring, and add
     the feature to the list in README.rst.
-3.  The pull request should work for Python 2.7, 3.5, 3.6, 3.7 and 3.8,
-    and for PyPy. Check
+3.  The pull request should work for Python 3.6, 3.7, 3.8, and 3.9.
+    Check
     <https://travis-ci.org/domvwt/esparto/pull_requests> and make sure
     that the tests pass for all supported Python versions.
 

diff --git a/docs/04-about/release-notes.md b/docs/04-about/release-notes.md
@@ -1,6 +1,15 @@
 Release Notes
 =============
 
+0.2.3 (2021-05-03)
+------------------
+
+-   Make documents 'print friendly'.
+-   Output to PDF with weasyprint.
+-   Export matplotlib plots as SVG by default.
+-   Use  `esparto.options` for configuring behaviour.
+
+
 0.2.2 (2021-04-24)
 ------------------
 

diff --git a/docs/04-about/roadmap.md b/docs/04-about/roadmap.md
@@ -1,8 +1,6 @@
-## New Features
-* Provide content support for
-    * Plotly
-    * Bokeh
-    * Altair
+Potential features:
+
 * Alternative themes
 * Additional Bootstrap components
+* User supplied Jinja templates
 * Custom CSS
diff --git a/docs/examples/iris-report.ipynb b/docs/examples/iris-report.ipynb
diff --git a/docs/index.md b/docs/index.md
@@ -1,9 +1,9 @@
 # Welcome
-Esparto is a super minimal frontend web framework written in Python. Its primary use is for generating shareable single page documents
+Esparto is a simple HTML and PDF document generator for Python. Its primary use is for generating shareable single page reports
 with content from popular analytics and data science libraries.
 
 ## Overview
-The library provides a streamlined API that lets users define their page in terms of
+The library features a streamlined API that defines pages in terms of
 sections, rows, and columns; and an intelligent wrapping system that automatically
 converts Python objects into content.
 
@@ -18,20 +18,25 @@ and fed into an HTML template with all style details and dependencies captured i
 Esparto supports content rendering within Jupyter Notebooks, allowing users to interactively
 and iteratively build documents without disrupting their workflow.
 
-## Features
+PDF conversion is provided by [Weasyprint](https://weasyprint.org/).
+
+### Features
 * Lightweight API
-* Jupyter Notebook support
 * No CSS or HTML required
 * Device responsive display
 * Self contained / inline dependencies
+* Jupyter Notebook support
+* Printer friendly formatting
+* PDF output
 * MIT License
 
-## Supported Content
-* Markdown text
+### Supported Content
+* Markdown
 * Images
-* Matplotlib figures
 * Pandas DataFrames
-* Bokeh objects
-* Plotly figures
+* Plots from:
+    * Matplotlib
+    * Bokeh
+    * Plotly
 
 <br>
diff --git a/esparto/__init__.py b/esparto/__init__.py
@@ -2,11 +2,14 @@
 """Top-level package for esparto."""
 
 from importlib.util import find_spec as _find_spec
-from typing import Set
+from pathlib import Path as _Path
+from typing import Set as _Set
 
 __author__ = """Dominic Thorn"""
 __email__ = "[email protected]"
-__version__ = "0.2.2"
+__version__ = "0.2.3"
+
+_MODULE_PATH: _Path = _Path(__file__).parent.absolute()
 
 
 _OPTIONAL_DEPENDENCIES: set = {
@@ -16,9 +19,10 @@
     "pandas",
     "bokeh",
     "plotly",
+    "weasyprint",
 }
 
-_INSTALLED_MODULES: Set[str] = {
+_INSTALLED_MODULES: _Set[str] = {
     x.name for x in [_find_spec(dep) for dep in _OPTIONAL_DEPENDENCIES] if x
 }
 
@@ -31,3 +35,4 @@
     Markdown,
 )
 from esparto._layout import Column, Page, Row, Section
+from esparto._options import options
diff --git a/esparto/_adaptors.py b/esparto/_adaptors.py
@@ -56,7 +56,7 @@ def content_adaptor_df(content: DataFrame) -> DataFramePd:
     from matplotlib.figure import Figure  # type: ignore
 
     @content_adaptor.register(Figure)
-    def content_adaptor_fig(content: Figure) -> FigureMpl:
+    def content_adaptor_mpl(content: Figure) -> FigureMpl:
         """Convert Matplotlib Figure to FigureMpl content."""
         return FigureMpl(content)
 
@@ -66,7 +66,7 @@ def content_adaptor_fig(content: Figure) -> FigureMpl:
     from bokeh.layouts import LayoutDOM as BokehObject  # type: ignore
 
     @content_adaptor.register(BokehObject)
-    def content_adaptor_bokeh_layout(content: BokehObject) -> FigureBokeh:
+    def content_adaptor_bokeh(content: BokehObject) -> FigureBokeh:
         """Convert Bokeh Layout to FigureBokeh content."""
         return FigureBokeh(content)