Package: mkreports
Mkreports packageIntroductionThe mkreports package makes it easy for you to write complex reports in mkdocs
including tables, graphics and programmatically defined output
using only python scripts. No Jupyter notebooks or workarounds such
as jupytext are needed.This methods works seamlessly with complex codebases, encourages
modularity and re-useability of code.Below is an example of a simple page. However, the documentation for this
package is also created withmkreports. The code can be found in thedocumentation.QuickstartIt is very easy to create new reports and pages. Below an example that
creates a report in theexample_reportdirectory and creates one pagequickstartin which a table and a plot of some data is shown together
with the code used to create those items.importpandasaspdimportplotnineasp9frommkreportsimportReportfromplotnine.dataimportmtcarsreport=Report.create("example_report",report_name="Mkreports documentations")p=report.page("quickstart")p.H1("Quickstart")p.P("""First, below the code that was used to create this page.It is a very brief example of an page with a table and an imageas well as some text, like here.""")p.CodeFile(__file__)p.P("""We are quickly analyzing the mtcars datasetthat is included with plotnine.""")withp.H2("Data as a table"):p.Tabulator(mtcars,add_header_filters=True,prettify_colnames=True)withp.H2("Some simple plots"):p.Image((p9.ggplot(mtcars,p9.aes("wt","mpg",color="factor(gear)"))+p9.geom_point()+p9.stat_smooth(method="lm")+p9.facet_wrap("~gear")))Now change to the folderexample_reportand runmkdocsserveand go to that page. The report will be shown in the browser. As the development
server of mkdocs supports automatic reload, as you run code, it will update automatically.
This is particularly convenient when running the IPython extension for interactive
analyses.Why write this package?In this reports we want to provide an easier way to create static
reports for data analysis. The main tool of choice in this space
are of course Jupyter notebooks which can also be converted to
static html files. So why another tool?The main reason is that having to switch to jupyter
notebooks breaks a workflow
in common editors such as vim as they don't natively
support jupyter notebooks. This problem can somewhat be
alleviated by using packages such asjupytextthat allow
for the seamless conversion between notebooks and python files.
The end results are ok but not quite satisfactory asOne python file corresponds to one output document
(which can get very long)Incremental execution is not possible (or at least hard to achieve)Regular debuggers such as pudb are not well supportedIt does not solve the issue that in remote ssh development
shells the viewing of graphics can be complicatedThe display options for code and complex tables are limited.Easily pass paramters to create reports. This is functionality
that for Jupyter is provided by tools such aspapermill, but
can be much easier achieved in native python.For this package, the planned features are:Simple and convenient ways to save and include graphics in markdown filesSimple way to include tables in markdown files, also for more complicated
javascript display optionsInclude code that was run in the output. For this, we would like
a tabbed style, so that the code is only visible when desired and not
all the time.Include an option to write the local variables of a stacktrace.Use this functionality together with IPython console to get a running
log of an analysis session.Using the development server ofmkdocs, live updates of sessions will be
possible, including live updates of long-running scripts.Packages used heremkdocs: A package to create static websites from markdown documents
that provides many features and is the bases for this package.mkdocs-material: The material theme for mkdocs that implements
some features that we are using.mdutils: A package that gives already many options to write out
markdown from python and that this package uses internally.