Metadata-Version: 2.1
Name: reportsrender
Version: 0.3.0
Summary: Execute and Render notebooks as HTML reports. 
Home-page: https://github.com/grst/reportsrender
License: UNKNOWN
Author: Gregor Sturm
Author-email: mail@gregor-sturm.de
Requires-Python: >= 3.6
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: R
Requires-Dist: docopt
Requires-Dist: ipython
Requires-Dist: jupytext>=1.3.0rc2
Requires-Dist: papermill
Requires-Dist: nbconvert
Requires-Dist: ipykernel
Requires-Dist: get_version
Requires-Dist: lxml
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: sphinx_autodoc_typehints; extra == "doc"
Requires-Dist: sphinx_rtd_theme; extra == "doc"
Requires-Dist: pytest; extra == "test"
Requires-Dist: matplotlib; extra == "test"
Provides-Extra: doc
Provides-Extra: test

Generate reproducible reports from Rmarkdown or jupyter notebooks
=================================================================
|travis| |docs| |black|

.. |travis| image:: https://travis-ci.com/grst/reportsrender.svg?branch=master
    :target: https://travis-ci.com/grst/reportsrender
    :alt: Build Status

.. |docs| image:: https://readthedocs.org/projects/reportsrender/badge/?version=latest
    :target: https://reportsrender.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
    
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: The uncompromising python formatter

Reportsrender allows to create reproducible, consistently looking HTML reports from
both jupyter notebooks and Rmarkdown files. It makes use of `papermill <https://github.com/nteract/papermill>`_
and `Rmarkdown <https://bookdown.org/yihui/rmarkdown/>`_ to execute notebooks and uses
`Pandoc <https://pandoc.org/>`_ to convert them to HTML.

**Features**:
 * two execution engines: papermill and Rmarkdown.
 * support any format supported by `jupytext <https://github.com/mwouts/jupytext>`_.
 * create self-contained HTML that can be shared easily.
 * hide inputs and/or outputs of cells.
 * parametrized reports

See the `documentation <https://reportsrender.readthedocs.io/>`_ for more details!

Getting started
================

* Execute an rmarkdown document to HTML using the Rmarkdown engine

::

    reportsrender rmd my_notebook.Rmd report.html

* Execute a parametrized jupyter notebook with papermill

::

    reportsrender papermill jupyter_notebook.ipynb report.html --params="data_file=table.tsv"


**TODO** add example notebooks.


Usage from command line
=======================

::

    reportsrender

    Execute and render a jupyter/Rmarkdown notebook.
    The `index` subcommand generates an index html
    or markdown file that links to html documents.

    Usage:
      reportsrender <notebook> <out_file> [--cpus=<cpus>] [--params=<params>] [--engine=<engine>]
      reportsrender index [--index=<index_file>] [--title=<title>] [--] <html_files>...
      reportsrender --help

    Arguments and options:
      <notebook>            Input notebook to be executed. Can be any format supported by jupytext.
      <out_file>            Output HTML file.
      -h --help             Show this screen.
      --cpus=<cpus>         Number of CPUs to use for Numba/Numpy/OpenBLAS/MKL [default: 1]
      --params=<params>     space-separated list of key-value pairs that will be passed
                            to papermill/Rmarkdown.
                            E.g. "input_file=dir/foo.txt output_file=dir2/bar.html"
      --engine=<engine>     Engine to execute the notebook. [default: auto]

    Arguments and options of the `index` subcommand:
      <html_files>          List of HTML files that will be included in the index. The tool
                            will generate relative links from the index file to these files.
      --index=<index_file>  Path to the index file that will be generated. Will be
                            overwritten if exists. Will auto-detect markdown (.md) and
                            HTML (.html) format based on the extension. [default: index.html]
      --title=<title>       Headline of the index. [default: Index]

    Possible engines are:
      auto                  Use `rmd` engine for `*.Rmd` files, papermill otherwise.
      rmd                   Use `rmarkdown` to execute the notebook. Supports R and
                            python (through reticulate)
      papermill             Use `papermill` to execute the notebook. Works for every
                            kernel available in the jupyter installation.






Installation
============

Conda (recommended):
^^^^^^^^^^^^^^^^^^^^
As this package dependes on both R and Python packages, I recommend
to install the package through `conda <https://docs.conda.io/en/latest/miniconda.html>`_.

I yet need to create a conda package and upload it on conda-forge, but you can create the following environment
and install the package:

::

    conda create -c bioconda -c conda-forge -n reportsrender \
          "python>=3.6" \
          "r-base>=3.5" \
          r-rmarkdown \
          r-reticulate \
          r-bookdown \
          flit \
          pandoc

    conda activate reportsrender
    flit installfrom github:grst/reportsrender




Manual install:
^^^^^^^^^^^^^^^

Get dependencies:
"""""""""""""""""

* Python
* `pandoc`_

For the Rmarkdown render engine additionally:

* R and the following packages:

::

    rmarkdown
    reticulate


Install from github:
""""""""""""""""""""

::

    pip install flit
    flit installfrom github:grst/reportsrender




