v4.0.0 (#112)

- New Features
    - Command line tools for printing default Jinja and CSS files
- Fixes
    - Config YAML now read with safe loader
- Deprecations
    - Removed CDN theme links
- Dependencies
    - Image content now supported without PIL

.coveragerc

@@ -23,3 +23,4 @@ exclude_lines =
 ignore_errors = True
 omit =
     tests/*
+    _cli.py

.flake8

@@ -6,4 +6,4 @@ ignore =
     E203, # whitespace before ':'
 per-file-ignores =
     __init__.py:E402, F401
-    _cdnlinks.py:E501
+    cdnlinks.py:E501

.gitignore

@@ -1,4 +1,5 @@
 # Scratch files for testing
+/scratch
 *scratch*.ipynb
 *scratch*.py
 image.jpg

Makefile

@@ -31,20 +31,20 @@ help:
 
 clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
 
-clean-build: ## remove build artifacts
+clean-build:
 	rm -fr build/
 	rm -fr dist/
 	rm -fr .eggs/
 	find . -name '*.egg-info' -exec rm -fr {} +
 	find . -name '*.egg' -exec rm -f {} +
 
-clean-pyc: ## remove Python file artifacts
+clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '*~' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -fr {} +
 
-clean-test: ## remove test and coverage artifacts
+clean-test:
 	rm -fr .tox/
 	rm -f .coverage
 	rm -fr htmlcov/
@@ -90,7 +90,7 @@ deploydocs: ## deploy docs to github pages
 	mkdocs gh-deploy
 
 class-diagram: ## make UML class diagram
-	pyreverse esparto -o png -f ALL --ignore _contentdeps.py,_options.py,_publish.py
+	pyreverse esparto -o png --ignore cdnlinks.py,contentdeps.py,_options.py,
 	mv classes.png devdocs/classes.png
 	rm packages.png
 
@@ -109,3 +109,6 @@ hooks: ## run pre-commit hooks on all files
 
 install: clean ## install the package to the active Python's site-packages
 	poetry install
+
+example_pages: ## make example pages
+	python tests/example_pages.py

README.md

@@ -57,7 +57,7 @@ Main Features
 - Responsive Bootstrap grid layout
 - Content adaptors for:
     - [Markdown][Markdown]
-    - [Images][Pillow]
+    - [Images]
     - [Pandas DataFrames][Pandas]
     - [Matplotlib][Matplotlib]
     - [Bokeh][Bokeh]
@@ -87,7 +87,6 @@ Dependencies
 
 #### Optional
 
-- [Pillow](https://python-pillow.org/) *(for image content)*
 - [weasyprint](https://weasyprint.org/) *(for PDF output)*
 
 License
@@ -125,7 +124,6 @@ Iris Report - [Webpage](https://domvwt.github.io/esparto/examples/iris-report.ht
 [Bootstrap]: https://getbootstrap.com/
 [Jinja]: https://jinja.palletsprojects.com/
 [Markdown]: https://www.markdownguide.org/
-[Pillow]: https://python-pillow.org/
 [Pandas]: https://pandas.pydata.org/
 [Matplotlib]: https://matplotlib.org/
 [Bokeh]: https://bokeh.org/

docs/02-user-guide/output-options.md

@@ -0,0 +1,69 @@
+# Output Options
+
+## CSS and Jinja
+
+Customising the look and feel of **esparto** pages is best achieved through
+modifying or replacing the Jinja template and CSS style sheets.
+Alternatively, CSS and Jinja sources can be passed to `es.options` as global
+defaults, or passed to the `es.Page` constructor using the `es.OutputOptions` class.
+
+```python
+# Updating global defaults.
+es.options.esparto_css = "./esparto.css"
+es.options.jinja_template = "./esparto.html.jinja"
+```
+
+```python
+# Using page level options.
+output_options = es.OutputOptions(
+    esparto_css="./esparto.css",
+    jinja_template="./esparto.html.jinja",
+)
+page = es.Page(output_options=output_options)
+```
+
+Options can be saved and loaded from disk using class methods.
+If an `esparto-config.yaml` file is found in the working directory, or at
+`~/esparto-data/esparto-config.yaml`, it will be loaded automatically when
+the library is imported.
+
+```python
+# These options will be loaded automatically for sessions in the same directory.
+output_options.save("./esparto-config.yaml")
+
+# These will be loaded only if no yaml file is found in the working directory.
+output_options.save("~/esparto-data/esparto-config.yaml")
+```
+
+## Printing Default Resources
+
+It's recommended to use the standard CSS and Jinja template files as a starting
+point for any changes.
+A command line interface is provided for printing the default resources.
+
+```bash
+# Print default esparto.css to `esparto.css`.
+python -m esparto print_esparto_css > esparto.css
+```
+
+```bash
+# Print default jinja template to `esparto.html.jinja`.
+python -m esparto print_jinja_template > esparto.html.jinja
+```
+
+```bash
+# Print default Bootstrap CSS to `bootstrap.css`.
+python -m esparto print_bootstrap_css > bootstrap.css
+```
+
+```bash
+# Print default output options to `esparto-config.yaml`.
+python -m esparto print_default_options > esparto-config.yaml
+```
+
+## More options
+
+For details on additional options please read the
+[documentation for the Options module.](/03-api-reference/options/)
+
+<br>

docs/02-user-guide/quick-start.md

@@ -1,5 +1,7 @@
 # Quick Start
 
+A brief overview of the main API features.
+
 ## Create a Page
 
 ```python

docs/03-api-reference/adaptors.md

@@ -1,4 +1,5 @@
-# esparto._adaptors
+# esparto.design.adaptors
+
 !!! info
     The `content_adaptor` function is called internally when an explicit `Content` class is not provided.
 
@@ -16,7 +17,6 @@
     {'New Page': [{'New Section': [{'Row 0': [{'Column 0': ['Markdown']}]}]}]}
     ```
 
-
-## ::: esparto._adaptors
+## ::: esparto.design.adaptors
 
 <br>

docs/03-api-reference/content.md

@@ -1,4 +1,4 @@
-# esparto._content
+# esparto.design.content
 
 !!! info
     `Content` classes will usually be inferred from the content object type.
@@ -12,22 +12,22 @@
 
     ```
 
-## ::: esparto._content.Content
+## ::: esparto.design.content.Content
 
 <br>
 
-## ::: esparto._content.Markdown
+## ::: esparto.design.content.Markdown
 
-## ::: esparto._content.DataFramePd
+## ::: esparto.design.content.DataFramePd
 
-## ::: esparto._content.FigureMpl
+## ::: esparto.design.content.FigureMpl
 
-## ::: esparto._content.FigureBokeh
+## ::: esparto.design.content.FigureBokeh
 
-## ::: esparto._content.FigurePlotly
+## ::: esparto.design.content.FigurePlotly
 
-## ::: esparto._content.Image
+## ::: esparto.design.content.Image
 
-## ::: esparto._content.RawHTML
+## ::: esparto.design.content.RawHTML
 
 <br>

docs/03-api-reference/layout.md

@@ -1,4 +1,4 @@
-# esparto._layout
+# esparto.design.layout
 
 !!! info
     `Layout` classes are accessed from the top level module.
@@ -11,27 +11,28 @@
 
     ```
 
-## ::: esparto._layout.Layout
+## ::: esparto.design.layout.Layout
+
 <br>
 
-## ::: esparto._layout.Page
+## ::: esparto.design.layout.Page
 
-## ::: esparto._layout.Section
+## ::: esparto.design.layout.Section
 
-## ::: esparto._layout.CardSection
+## ::: esparto.design.layout.CardSection
 
-## ::: esparto._layout.Row
+## ::: esparto.design.layout.Row
 
-## ::: esparto._layout.CardRow
+## ::: esparto.design.layout.CardRow
 
-## ::: esparto._layout.CardRowEqual
+## ::: esparto.design.layout.CardRowEqual
 
-## ::: esparto._layout.Column
+## ::: esparto.design.layout.Column
 
-## ::: esparto._layout.Card
+## ::: esparto.design.layout.Card
 
-## ::: esparto._layout.Spacer
+## ::: esparto.design.layout.Spacer
 
-## ::: esparto._layout.PageBreak
+## ::: esparto.design.layout.PageBreak
 
 <br>

docs/03-api-reference/options.md

@@ -1,7 +1,10 @@
 # esparto._options
 
 !!! info
-    Default output options are configured through `es.options`.
+    Default options are configured through `es.options`, page level options can
+    be passed to the `Page` constructor.
+
+    Please read [the user guide](/02-user-guide/output-options) for more details.
 
 ## ::: esparto._options.OutputOptions
 

docs/03-api-reference/publish.md

@@ -1,4 +1,4 @@
-# esparto._publish
+# esparto.publish.output
 
 !!! info
     Publishing methods are accessed via Layout classes.
@@ -17,10 +17,10 @@
 
     ```
 
-## ::: esparto._publish.publish_html
+## ::: esparto.publish.output.publish_html
 
-## ::: esparto._publish.publish_pdf
+## ::: esparto.publish.output.publish_pdf
 
-## ::: esparto._publish.nb_display
+## ::: esparto.publish.output.nb_display
 
 <br>

docs/04-about/release-notes.md

@@ -1,6 +1,18 @@
 Release Notes
 =============
 
+4.0.0 (2022-04-19)
+------------------
+
+- New Features
+    - Command line tools for printing default Jinja and CSS files
+- Fixes
+    - Config YAML now read with safe loader
+- Deprecations
+    - Removed CDN theme links
+- Dependencies
+    - Image content now supported without PIL
+
 3.0.2 (2022-02-28)
 ------------------
 

esparto/__init__.py

@@ -15,13 +15,13 @@
 
 __author__ = """Dominic Thorn"""
 __email__ = "[email protected]"
-__version__ = "3.0.2"
+__version__ = "4.0.0"
 
 _MODULE_PATH: _Path = _Path(__file__).parent.absolute()
 
 
 _OPTIONAL_DEPENDENCIES: _Set[str] = {
-    "PIL",
+    "PIL",  # Only used for type checking and conversion
     "IPython",
     "matplotlib",
     "pandas",
@@ -34,8 +34,8 @@
     x.name for x in [_find_spec(dep) for dep in _OPTIONAL_DEPENDENCIES] if x
 }
 
-from esparto._cdnlinks import bootstrap_cdn_themes
-from esparto._content import (
+from esparto._options import OutputOptions, options
+from esparto.design.content import (
     DataFramePd,
     FigureBokeh,
     FigureMpl,
@@ -44,7 +44,7 @@
     Markdown,
     RawHTML,
 )
-from esparto._layout import (
+from esparto.design.layout import (
     Card,
     CardRow,
     CardRowEqual,
@@ -56,6 +56,3 @@
     Section,
     Spacer,
 )
-from esparto._options import OutputOptions, options
-
-options._autoload()

esparto/__main__.py

@@ -0,0 +1,4 @@
+from esparto import _cli
+
+if __name__ == "__main__":
+    _cli.main()