Create version 1.0.0

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+max-line-length = 88

.github/workflows/build_and_upload.yml

@@ -8,9 +8,9 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: '3.x'
       - name: Install dependencies
@@ -20,7 +20,7 @@ jobs:
       - name: Build package
         run: python -m build
       - name: Publish package
-        uses: pypa/gh-action-pypi-publish@master
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/tests.yml

@@ -1,26 +1,28 @@
-name: Python package
+name: Tests
 
-on: [push]
+on: [ push ]
 
 jobs:
-  build:
-
+  test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
 
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          if [ -f requirements_test.txt ]; then pip install -r requirements_test.txt; fi
-          if [ -f requirements_examples.txt ]; then pip install -r requirements_examples.txt; fi
-      - name: Test with pytest
+          pip install tox
+      - name: Run tox
+        env:
+          TOXENV: "py${{ matrix.python-version }}-core-tests"
         run: |
-          pytest --doctest-modules --junitxml=junit/test-results.xml --cov=pyreball --cov-report=xml --cov-report=html tests/
+          TOXENV=${{ env.TOXENV }}
+          TOXENV=${TOXENV//.}
+          tox -e $TOXENV,mypy,flake8,ufmt

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/omnilib/ufmt
+    rev: v2.1.0
+    hooks:
+      - id: ufmt
+        additional_dependencies:
+          - black == 23.7.0
+          - usort == 1.0.7

.readthedocs.yaml

@@ -0,0 +1,25 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+  jobs:
+    pre_build:
+      - find docs/examples -name "*.py" -exec pyreball {} \;
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - requirements: requirements_examples.txt
+    # Install our python package before building the docs
+    - method: pip
+      path: .
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+
+formats:
+  - pdf
+  - epub

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.0.0 (2023-09-15)
+
+- Added new text elements `div()` and `span()`. Added new parameters to HTML elements - in particular `cl` and `attrs`.
+- Replaced `print_html()` function with `print()`.
+- Replaced `print_code()` function with `print_source_code()`.
+- Replaced `plot_graph()` with `print_figure()`.
+- Removed `plot_multi_graph`.
+- Replaced code-prettify with highlight.js for code blocks.
+- `print_h1`, ..., `print_h6` functions can now take a `Reference` object.
+- Added `--config-path` CLI option, changed how `pyreball-generate-config` command works and how the config paths are
+  handled.
+- Updated CLI arguments and config parameters for tables, figures and code blocks.
+- Updated template files.
+- Updated to newer versions of 3rd party dependencies for example.
+- Created documentation at readthedocs.
 
 ## 0.1.1 (2021-09-14)
 

README.md

@@ -1,69 +1,75 @@
 # Pyreball
 
-Python reporting tool that generates HTML reports from Python scripts.
+<p style="text-align: center">
+
+![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue)
+[![pypi](https://img.shields.io/pypi/v/pyreball.svg)](https://pypi.python.org/pypi/pyreball)
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Tests](https://github.com/karelvaculik/pyreball/actions/workflows/tests.yml/badge.svg)](https://github.com/karelvaculik/pyreball/actions/workflows/tests.yml)
+
+</p>
+
+Pyreball is a Python reporting tool that generates HTML reports from Python scripts.
 
 Main features:
 
-- Plots in altair, plotly, bokeh, and matplotlib (and thus also seaborn etc.).
-- Sortable and scrollable tables from pandas DataFrame.
+- Plots in [Vega-Altair](https://altair-viz.github.io/index.html), [Plotly](https://plotly.com/), [Bokeh](https://bokeh.org/), and [Matplotlib](https://matplotlib.org/) (and thus also [Seaborn](https://seaborn.pydata.org/) etc.).
+- Interactive tables based on [DataTables](https://datatables.net/) library and created from [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).
 - Basic text formatting such as headings, emphasis, and lists.
 - Hyperlinks, references and table of contents.
 
-The main motivation is to allow the users to
-create persistent reports in the form of interactive HTML pages from scripts retaining the Python syntax. The advantage
-of *regular* Python scripts is that they are easy to maintain, can be refactored quickly through various IDEs, etc.
+The main motivation is to allow users to create persistent reports in the form of HTML pages from scripts retaining the
+Python syntax.
+The advantage of using *regular* Python scripts as the source of these HTML pages is that they are easy to maintain, can
+be refactored quickly through various IDEs, etc.
 
 Pyreball is designed not to require any dependencies, unless you decide to use them. For example, if you decide to print
-pandas DataFrames to tables and plot altair charts, you need to install pandas and altair.
-
-Note that Pyreball is still in early stages of development, so there can be some breaking changes between released 
-versions.
+pandas DataFrames to HTML tables and plot altair charts, you need to install pandas and altair.
 
 ## Install
 
 ```shell
 pip install pyreball
 ```
 
-## Usage
+## Quick Example
 
 Create a regular python script, for example `report.py`:
 
 ```python
-import pandas as pd
 import matplotlib.pyplot as plt
-import seaborn as sns
-
+import pandas as pd
 import pyreball as pb
+import seaborn as sns
 
 pb.set_title("Pyreball Illustration")
 
 pb.print_h1("Introduction")
 
 pb.print_div(
     "Pyreball has many features, among others:",
-    pb.ul(
-        'Plots in altair, plotly, bokeh, and matplotlib (and thus also seaborn etc.).',
-        'Sortable and scrollable tables from pandas DataFrame.',
+    pb.ulist(
+        "Plots in altair, plotly, bokeh, and matplotlib (and thus also seaborn etc.).",
+        "Sortable and scrollable tables from pandas DataFrame.",
         f'Basic text formatting such as {pb.bold("headings")}, {pb.em("emphasis")}, and {pb.code("lists")}.',
         f'{pb.link("hyperlinks", "https://www.python.org/")}, references and table of contents.',
-    )
+    ),
 )
 
 pb.print_h1("Tables and Plots")
 
 # Print a table
-df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 6, 5]})
+df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 6, 5]})
 pb.print_table(df, caption="A data table.")
 
 # Plot a graph
 fig, ax = plt.subplots()
-sns.lineplot(x='x', y='y', ax=ax, data=df)
-ax.set(xlabel='x', ylabel='y')
-pb.plot_graph(fig, caption="The first plot.")
+sns.lineplot(x="x", y="y", ax=ax, data=df)
+ax.set(xlabel="x", ylabel="y")
+pb.print_figure(fig, caption="The first plot.")
 ```
 
-In this particular example, we use several 3rd party packages so we also need to install them:
+In this particular example, we are using a few 3rd party packages, so let's install them too:
 
 ```shell
 pip install pandas matplotlib seaborn
@@ -79,80 +85,9 @@ pyreball report.py
 
 ![Pyreball Screenshot](pyreball_result_screenshot.png)
 
-Script `report.py` and a few other examples can be found in `examples` folder. For example, `longer_report.py` 
-illustrates most of the Pyreball's features, while `sample_plots.py` shows different plotting libraries. 
-To install all dependencies needed for these examples, run:
+## Documentation
 
-```shell
-pip install -r requirements_examples.txt
-```
-
-## Pyreball Settings
-
-The default parameters are stored in Pyreball's `config.ini` file. This config looks like
-this:
-
-```
-[Parameters]
-toc = yes
-align-tables = center
-numbered-tables = yes
-sortable-tables = no
-full-tables = yes
-align-plots = center
-numbered-plots = yes
-matplotlib-format = svg
-matplotlib-embedded = yes
-numbered-headings = yes
-page-width = 80
-keep-stdout = yes
-```
-
-This config says that each table should be centered, each page should have a table of contents (toc), etc. 
-It is not recommended to modify the default Pyreball's config file. Instead, run the following command to generate 
-the copy of configs:
-
-```shell
-pyreball-generate-config
-```
-
-By default, the configs will be copied to `<HOME>/.pyreball/` directory, which can be changed by optional 
-`--output-dir` parameter. Once generated, the `config.ini` can be modified and it will be used by Pyreball.
-Each of these values can be also overridden by specific cli option of `pyreball` command (e.g. `--center-tables=no`). 
-This is useful if non-default settings should be applied to a specific file(s). For example, the following command 
-overrides parameters `full-tables` and `page-width`:
-
-```shell
-pyreball --full-tables=no --page-width=100 script.py
-```
-
-Some parameters can be overridden even on the level of individual function calls. For example, parameter `center`
-of `print_table` function can override both `--center-tables` cli option and `center-tables` in `config.ini`.
-
-To summarize, Pyreball reads settings from its default config file. If a config file is generated by 
-`pyreball-generate-config`, then this generated config is used instead. If cli parameters are provided, they
-override the settings from config files. If parameters are set via Python function parameters, they override everything.
-
-Pyreball uses the name of the input script and its directory to derive the path of the output file by default.
-In order to change this output path, use `--output-path` option, for example:
-
-```shell
-pyreball --output-path=report_123.html report.py
-pyreball --output-path=mydir/mysubdir/report_456.html report.py
-```
-
-
-Run `pyreball --help` to see the command help. It also shows the possible values for both cli and `config.ini`.
-
-### Custom Script Arguments
-
-Sometimes, we might want to pass custom arguments into our Python script that is used to generate the report.
-To do so, pass `--` and all your arguments after all Pyreball's regular arguments.
-For example, you can try this on `custom_arguments.py` example script by calling:
-
-```shell
-pyreball --page-width=90 custom_arguments.py -- --sum 23 25 24
-```
+See [documentation](https://pyreball.readthedocs.io/) for more examples and information about Pyreball.
 
 ## Setting up Pyreball in PyCharm
 
@@ -165,7 +100,6 @@ In PyCharm, go `PyCharm -> Preferences... -> Tools -> External Tools` and add a
 - Program: `$PyInterpreterDirectory$/pyreball`
 - Arguments: `$FilePath$`
 - Working directory: `$ProjectFileDir$`
-- Advanced Options -> Output filters: `$FILE_PATH$:$LINE$:$COLUMN$:.*`
 
 Then it is possible to run `pyreball` on the open Python script by clicking
 `Tools -> External Tools -> pyreball` or by right-clicking on the script and then selecting

docs/api/pyreball_html.md

@@ -0,0 +1 @@
+::: pyreball.html

docs/api/pyreball_text.md

@@ -0,0 +1 @@
+::: pyreball.text