1.3.0 (#56)

- New Layout class - Card: Bordered container for grouping content - Updated Content class - FigureMpl: SVG rendered plots now flex up to 150% of original size - Other - Defined string and repr representations for current settings - Updated CSS so maintain distance from header if main title is not defined - Updated content adaptor to allow other Layout objects as valid children for Column
domvwt · Jul 19, 2021 · 711741f · 711741f
1 parent 0d9ecd6
commit 711741f
Show file tree

Hide file tree

Showing 13 changed files with 136 additions and 84 deletions.
diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@ esparto
 [![Build Status](https://travis-ci.com/domvwt/esparto.svg?branch=main)](https://travis-ci.com/domvwt/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)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/esparto)
 
 
 ## Introduction

diff --git a/docs/04-about/release-notes.md b/docs/04-about/release-notes.md
@@ -1,6 +1,23 @@
 Release Notes
 =============
 
+1.3.0 (2021-07-19)
+------------------
+-   New Layout class
+    -   Card: Bordered container for grouping content
+-   Updated Content class
+    -   FigureMpl: SVG rendered plots now flex up to 150% of original size
+-   Other
+    -   Defined string and repr representations for current settings
+    -   Updated CSS so maintain distance from header if main title is not defined
+    -   Updated content adaptor to allow other Layout objects as valid children for Column
+
+
+1.2.0 (2021-06-28)
+------------------
+-   Implicitly read markdown text files
+
+
 1.1.0 (2021-06-18)
 ------------------
 -   New Layout classes
@@ -18,79 +35,69 @@ Release Notes
 
 1.0.1 (2021-06-01)
 ------------------
--   Update dependencies.
--   Fix SVG rendering in PDF.
--   Update docs and examples.
+-   Update dependencies
+-   Fix SVG rendering in PDF
+-   Update docs and examples
 
 
 1.0.0 (2021-05-31)
 ------------------
-
--   Improve API.
--   Responsive SVG plots.
--   Update Jinja template to remove branding.
--   Refactor codebase.
+-   Improve API
+-   Responsive SVG plots
+-   Update Jinja template to remove branding
+-   Refactor codebase
 
 
 0.2.5 (2021-05-06)
 ------------------
-
--   Fix linting errors.
--   Add dataclasses dependency for Python < 3.7.
+-   Fix linting errors
+-   Add dataclasses dependency for Python < 3.7
 
 
 0.2.4 (2021-05-04)
 ------------------
-
--   Fix bug corrupting document titles.
--   Lazy load the content dependency dict.
--   Remove unused code.
+-   Fix bug corrupting document titles
+-   Lazy load the content dependency dict
+-   Remove unused code
 
 
 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.
+-   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)
 ------------------
-
--   Fix notebook display for Colab.
+-   Fix notebook display for Colab
 
 
 0.2.1 (2021-04-24)
 ------------------
-
--   Add Bootstrap dependencies for relevant content classes.
--   Inherit FigureBokeh height from Bokeh object.
--   Fix issues with in-notebook content rendering.
+-   Add Bootstrap dependencies for relevant content classes
+-   Inherit FigureBokeh height from Bokeh object
+-   Fix issues with in-notebook content rendering
 
 
 0.2.0 (2021-04-23)
 ------------------
-
--   Add support for Bokeh and Plotly.
+-   Add support for Bokeh and Plotly
 
 
 0.1.2 (2021-04-09)
 ------------------
-
--   Relax dependency on Pillow to allow versions >=7.0.0 and <9.0.0.
+-   Relax dependency on Pillow to allow versions >=7.0.0 and <9.0.0
 
 
 0.1.1 (2021-04-08)
 ------------------
-
--   Update package metadata for pypi.
+-   Update package metadata for pypi
 
 
 0.1.0 (2021-04-07)
 ------------------
-
--   First public release.
+-   First public release
 
 <br>
diff --git a/esparto/__init__.py b/esparto/__init__.py
@@ -87,7 +87,7 @@
 
 __author__ = """Dominic Thorn"""
 __email__ = "[email protected]"
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 _MODULE_PATH: _Path = _Path(__file__).parent.absolute()
 
@@ -115,5 +115,5 @@
     Markdown,
     RawHTML,
 )
-from esparto._layout import Column, Page, PageBreak, Row, Section, Spacer
+from esparto._layout import Card, Column, Page, PageBreak, Row, Section, Spacer
 from esparto._options import options
diff --git a/esparto/_adaptors.py b/esparto/_adaptors.py
@@ -1,6 +1,7 @@
 from functools import singledispatch
 from mimetypes import guess_type
 from pathlib import Path
+from typing import Union
 
 from esparto import _INSTALLED_MODULES
 from esparto._content import (
@@ -12,12 +13,13 @@
     Image,
     Markdown,
 )
+from esparto._layout import Layout
 
 
 @singledispatch
-def content_adaptor(content: Content) -> Content:
+def content_adaptor(content: Content) -> Union[Content, Layout]:
     """
-    Wrap content in the required class.
+    Wrap content in the required class. If Layout object is passed, return unchanged.
 
     Args:
       content (Any): Any content to be added to the document.
@@ -46,8 +48,14 @@ def content_adaptor_core(content: str) -> Content:
     return Markdown(content)
 
 
+@content_adaptor.register(Layout)
+def content_adaptor_layout(content: Layout) -> Layout:
+    """If Layout object is passed, return unchanged."""
+    return content
+
+
 @content_adaptor.register(Path)
-def content_adaptor_path(content: Path) -> Content:
+def content_adaptor_path(content: Path) -> Union[Content, Layout]:
     """Convert text or image path to Markdown or Image content."""
     content_str = str(content)
     return content_adaptor_core(content_str)

diff --git a/esparto/_content.py b/esparto/_content.py
@@ -212,10 +212,9 @@ def to_html(self, **kwargs) -> str:
         image_encoded = _image_to_base64(image)
         html = (
             "<figure class='text-center p-3'>"
-            + "<img class='img-fluid figure-img rounded' "
-            + f"alt='{self.alt_text}' "
-            + f"src='data:image/png;base64,{image_encoded}' "
-            + ">"
+            "<img class='img-fluid figure-img rounded' "
+            f"alt='{self.alt_text}' "
+            f"src='data:image/png;base64,{image_encoded}'>"
         )
 
         if self.caption:
@@ -265,7 +264,7 @@ class FigureMpl(Content):
       figure (plt.Figure): A Matplotlib figure.
       width (int): Width in pixels. (default = '100%')
       height (int): Height in pixels. (default = 'auto')
-      output_format (str): One of 'svg', 'png', or 'esparto.options'. (default = 'options.matplotlib_output_format')
+      output_format (str): 'svg' or 'png'. (default = None)
 
     """
 
@@ -314,11 +313,12 @@ def to_html(self, **kwargs):
                 xml = responsive_svg_mpl(xml)
                 inner = xml
 
+            max_scale_up = 1.5
             html = (
                 "<div class='row justify-content-center p-0 m-0' "
-                + "style='width: 100%; height: auto;'>\n"
-                + f"<div class='col p-0 m-0' style='width: {self.width}; max-width: {int(width)}px; height: auto;'>"
-                + f"{inner}\n</div>\n</div>\n"
+                "style='width: 100%; height: auto;'>\n"
+                f"<div class='col p-0 m-0' style='max-width: {int(width * max_scale_up)}px; height: auto;'>"
+                f"{inner}\n</div>\n</div>\n"
             )
 
             return html

diff --git a/esparto/_contentdeps.py b/esparto/_contentdeps.py
@@ -3,10 +3,10 @@
 from collections import UserDict
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Set
+from typing import List, Optional, Set
 
 from esparto import _INSTALLED_MODULES, _MODULE_PATH
-from esparto._options import get_dep_source_from_options, options
+from esparto._options import get_dep_source_from_options
 
 
 @dataclass
@@ -70,9 +70,7 @@ def lazy_content_dependency_dict() -> ContentDependencyDict:
     return content_dependency_dict
 
 
-def resolve_deps(
-    required_deps: Set[str], source: str = options.default
-) -> ResolvedDeps:
+def resolve_deps(required_deps: Set[str], source: Optional[str]) -> ResolvedDeps:
     resolved_deps = ResolvedDeps()
 
     source = str(get_dep_source_from_options(source))

diff --git a/esparto/_layout.py b/esparto/_layout.py
@@ -5,7 +5,6 @@
 from pprint import pformat
 from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Set, Type, Union
 
-from esparto._options import options
 from esparto._publish import nb_display, publish_html, publish_pdf
 from esparto._utils import clean_attr_name, clean_iterator, get_matching_titles
 
@@ -348,7 +347,7 @@ def save(
         self,
         filepath: str = "./esparto-doc.html",
         return_html: bool = False,
-        dependency_source=options.default,
+        dependency_source: str = None,
     ) -> Optional[str]:
         """
         Save document to HTML file.
@@ -358,7 +357,7 @@ def save(
         Args:
           filepath (str): Destination filepath.
           return_html (bool): If True, return HTML as a string.
-          dependency_source (str): One of 'cdn', 'inline', or 'esparto.options'.
+          dependency_source (str): 'cdn' or 'inline'.
 
         Returns:
           Document rendered as HTML. (If `return_html` is True)
@@ -378,15 +377,15 @@ def save_html(
         self,
         filepath: str = "./esparto-doc.html",
         return_html: bool = False,
-        dependency_source=options.default,
+        dependency_source: str = None,
     ) -> Optional[str]:
         """
         Save document to HTML file.
 
         Args:
           filepath (str): Destination filepath.
           return_html (bool): If True, return HTML as a string.
-          dependency_source (str): One of 'cdn', 'inline', or 'esparto.options'.
+          dependency_source (str): 'cdn' or 'inline'.
 
         Returns:
           Document rendered as HTML. (If `return_html` is True)
@@ -425,7 +424,7 @@ def save_pdf(
             return html
         return None
 
-    _title_tags = "<h1 class='display-4 my-3'>{title}</h1>"
+    _title_tags = "<h1 class='display-4 mb-3'>{title}</h1>"
     _body_tags = "<main class='container px-2' id='{identifier}'>{children}</main>"
 
     @property
@@ -465,7 +464,7 @@ class Row(Layout):
     """
 
     _title_tags = "<div class='col-12'><h5 class='px-1 mb-3'>{title}</h5></div>"
-    _body_tags = "<div class='row mb-3' id='{identifier}'>{children}</div>"
+    _body_tags = "<div class='row mb-3' style='align-items: flex-start;' id='{identifier}'>{children}</div>"
     _parent_class = Section
 
     @property
@@ -491,6 +490,25 @@ def _child_class(self):
         raise NotImplementedError
 
 
+class Card(Column):
+    """A Card can be used in place of a Column for grouping related items.
+    Child items will be vertically stacked by defualt. Horizontal distribution
+    can be achieved by nesting content inside a Row.
+
+    Args:
+        title (str): Used as a title within the document and as a key value.
+        children (list): Child items defining layout and content.
+
+    """
+
+    _title_tags = "<h5 class='card-title'>{title}</h5>"
+    _body_tags = (
+        "<div class='col-lg mx-2 mb-3 border rounded' style='padding: 1rem;' id='{identifier}'>"
+        "{children}"
+        "</div>"
+    )
+
+
 class Spacer(Column):
     """Empty Column for making space within a Row."""