could you provide more clarification on without hidden state that supports any text editor as written in handout's README?

Consider making show() and alias.

Recommended by user unbalancedparen on Twitter. We should add a CONTRIBUTING.md to the repository and roughly states:

• Contributions are welcome
• Check out the Github issues and join the discussions
• Comment on an issue with "help wanted" tag to discuss potential solutions
• Implement the feature and send a PR
• The is a discussion tag that can be used for discussion features or meta discussions (this acts as our forum/slack channel)

Anything else I should mention?

Use case:
I'm using Handout as an alternative to ShareLatex/Notebook for my homework reports. The reports consists many plots and a few comments.

What I want to be able to do
I want to hide some parts of my code that are not relevant to the reader of the report, but necessary to create my plots. For instance, I usually have several lines specifying formatting of my pyplots.

Thanks

Hi, all.
I want to make sure how handout renders the scripts. It looks like doc.show() will execute _generate method, append all the blocks, then render all of them, right? And then when doc.show() gets called again, it will re-render the whole blocks except with more lineno?

With this behavior, if someone writes more lines of script, maybe with more figures or videos, does it affect the time we need to run the script?

Is there any plan or current extension which allows real time view in VS Code / Atom / Sublime Text for this great package?

Adding custom CSS is possible in two ways:

doc.add_html('<style></style>')
doc.add_html('<link rel="stylesheet" href="path/to/style.css">')

We could add doc.add_style(filename) that copies the file into the output directory for the user.

I run example.py in IPython console in Spyder and it seems that console output gets proportional to the number of times I have run the script. On the first run in new kernel I get just single message, one per call of handout.Handout instance method.

This is what I get on the fifth run:

Iteration 0
Iteration 0
Iteration 0
Iteration 0
Iteration 0
Iteration 0
Iteration 1
Iteration 1
Iteration 1
Iteration 1
Iteration 1
Iteration 1
Iteration 2
Iteration 2
Iteration 2
Iteration 2
Iteration 2
Iteration 2
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Saved figure: output\figure-0.png
Saved figure: output\figure-0.png
Saved figure: output\figure-0.png
Saved figure: output\figure-0.png
Saved figure: output\figure-0.png
Saved figure: output\figure-0.png
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Saved figure: output\figure-1.png
Saved figure: output\figure-1.png
Saved figure: output\figure-1.png
Saved figure: output\figure-1.png
Saved figure: output\figure-1.png
Saved figure: output\figure-1.png
Saved figure: output\figure-2.png
Saved figure: output\figure-2.png
Saved figure: output\figure-2.png
Saved figure: output\figure-2.png
Saved figure: output\figure-2.png
Saved figure: output\figure-2.png
Saved figure: output\figure-3.png
Saved figure: output\figure-3.png
Saved figure: output\figure-3.png
Saved figure: output\figure-3.png
Saved figure: output\figure-3.png
Saved figure: output\figure-3.png
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html
Handout written to: output\index.html

Maybe not a bug, but it would have felt more confortable the handout.Handout instance made just a single print to the screen per call.

I run the script as runfile('D:/github/handout/example.py', wdir='D:/github/handout')

Hi and thanks for this package, I just had a couple of questions if you don't mind me asking since I couldn't find any answers in the readme.

1. Is it possible to export the document into latex?
2. Will you be releasing a conda package?

Thanks!

Let's collect key topics and then put together a user guide. Points that came up already:

• Comparison to related projects (when (not) to use it)
• Converting HTML via pandoc
• Using custom text renderers (for flow charts etc)
• Adding JS and CSS in general
• Multiple handouts for static websites
• Updating the doc while the script runs for training ML models

The output format is currently HTML, which can then be printed as PDF from the browser. It could be nice to directly export to PDF, ipynb and other formats.

doc.show(tabs=index)

Hi Dani!

1st issue!😄

Just tried your example and made it run by executing from the terminal. But I already struggled with setting up my Atom IDE so I can execute it from there. I used "atom-run-python" and "atom-python-virtualenv" so I can execute my script on the go in the related virtualenv. Executing it with this setting leads to some kind of bug. The plots are located in the same directory as "example.py" ("example.py-L48-0.png", etc.) while HTML, js, css are placed in the output directory.

Since it might be related to the executing directory I tried to execute "python example.py" in the terminal but in its parent directory (python repo/example.py). This even leads to an execution error:

(venv) C:\Users\Thomas\HPI> python .\MA\example.py
Traceback (most recent call last):
  File ".\MA\example.py", line 48, in <module>
    doc.display(fig)  # Display the figure below this line.
  File "C:\Users\Thomas\HPI\MA\venv\lib\site-packages\handout\handout.py", line 26, in display
    figure.savefig(filename)
  File "C:\Users\Thomas\HPI\MA\venv\lib\site-packages\matplotlib\figure.py", line 1834, in savefig
    self.canvas.print_figure(fname, **kwargs)
  File "C:\Users\Thomas\HPI\MA\venv\lib\site-packages\matplotlib\backend_bases.py", line 2267, in print_figure
    **kwargs)
  File "C:\Users\Thomas\HPI\MA\venv\lib\site-packages\matplotlib\backends\backend_agg.py", line 512, in print_png
    filename_or_obj = open(filename_or_obj, 'wb')
FileNotFoundError: [Errno 2] No such file or directory: 'output\\.\\MA\\example.py-L48-0.png'

An empty output directory is created next to my repository.

Environment

• Windows 8
• Python 3.6.0
• handout==0.2.2

Hope this helps you tracking down this bug,
Thomas

I got to use handout for a simple jupyter-like visualisation and was adding an image in the middle of the file.

The image does show up, but at the end of file. This is not an intended behaviour, right?

What can be causing it? I initially thought Spyder/ipython session could be the problem,
but a standalone intepreter run does the same.

Here is my output:
https://epogrebnyak.github.io/sna-ru/handout/index.html

Here is the code:
epogrebnyak/sna-ru#1

We can already hide individual lines from the handout using # handout: exclude.

It would be great to allow excluding ranges via:

# handout: begin-exclude
<Python code here>
# handout: end-exclude

Media added inside such blocks will still be shown.

This will make it easy to create reports that only include text and media, but not code.

Similar to #13 the name of an output html file can be {__file__}.html, instead of hardcoded index.html (if it is possible to track and pass source file name, but seems realistic).

This way model.py will have an output model.html. This feature should open the way to ensembles/collections of handouts.

Hi, it would be great to have a handout that could generate/display a Dataframe table. Might be something like doc.add_dataframe(df)

Branched from #10 (comment):

@danijar would you be open to a PR that uses the Python AST. Looking at this request and others, it might be worth to consider making the change to AST parsing, sooner rather then later. For instance one advantage could be, is that you choose to hide the doc.* code.

Hi @eiso, yes I think switching to AST could be good. I'd definitely look forward to a PR, although it'll likely take some back and forth until we converge on a design that works well for the library.

Hi would it be too much trouble to ask for a conda package?

What is the purpose of look-through in Handout class:

for info in inspect.stack():
      if info.filename == __file__:
        continue
      break

My first impression is that nothing happens in the loop.

Hard to understand the package without it. Finding one's way back to github is probably beyond many.

doc.add_video(tensor_or_filename) to create GIFs or display anything the browser can display (e.g. MP4).

KaTeX and MathJax seem like great options.

Current status: LaTeX is included by default now. However, it is loaded from a URL and we are working on bundling a local copy with the package for offline viewing.

Just a quick note to ask if you are aware of pweave project, which, albeit without an active maintainer at the moment, does exactly the same. Supports markdown with python snippets, modeled after Rstudio Rmd format, or python with special comments as in this project. Supports matplotlib as well bokeh graphics (I have patches for altair, also web based and with interactions).

Instead of writing a message every time saved, there should be one message in the beginning that states the location of the handout.

Hey,
I am facing this error:

python3 example.py
Iteration 0
Iteration 1
Iteration 2
Handout written to: output/index.html
Saved figure: output/figure-0.png
Handout written to: output/index.html
Saved figure: output/figure-1.png
Saved figure: output/figure-2.png
Saved figure: output/figure-3.png
Handout written to: output/index.html
Traceback (most recent call last):
File "example.py", line 69, in
doc.add_image(image_a, 'png', width=0.4)
File "~/handout/handout.py", line 52, in add_image
imageio.imsave(os.path.join(self._directory, filename), image)
File "/usr/local/lib/python3.5/dist-packages/imageio/core/functions.py", line 259, in imwrite
writer = get_writer(uri, format, "i", **kwargs)
File "/usr/local/lib/python3.5/dist-packages/imageio/core/functions.py", line 180, in get_writer
format = formats.search_write_format(request)
File "/usr/local/lib/python3.5/dist-packages/imageio/core/format.py", line 706, in search_write_format
if format.can_write(request):
File "/usr/local/lib/python3.5/dist-packages/imageio/core/format.py", line 192, in can_write
return self._can_write(request)
File "/usr/local/lib/python3.5/dist-packages/imageio/plugins/pillow.py", line 113, in _can_write
Image = self._init_pillow()
File "/usr/local/lib/python3.5/dist-packages/imageio/plugins/pillow.py", line 88, in _init_pillow
"Imageio Pillow plugin requires " "Pillow, not PIL!"
ImportError: Imageio Pillow plugin requires Pillow, not PIL!

From #20 (comment):

doc.add_text('<p style="page-break-before: always">')

We can add doc.add_pagebreak() if this is helpful, especially once we have a LaTeX exporter that could also support this.

For my workflow, the greatest problem with this package at the moment is that it throws an error when running handout.Handout() in an interactive shell:

handout.Handout('/tmp')
Traceback (most recent call last):
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/site-packages/IPython/core/interactiveshell.py", line 3325, in run_code
    exec(code_obj, self.user_global_ns, self.user_ns)
  File "<ipython-input-4-d909ee1709cf>", line 1, in <module>
    handout.Handout('/tmp')
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/site-packages/handout/handout.py", line 25, in __init__
    self._source_text = inspect.getsource(module)
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/inspect.py", line 973, in getsource
    lines, lnum = getsourcelines(object)
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/inspect.py", line 955, in getsourcelines
    lines, lnum = findsource(object)
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/inspect.py", line 768, in findsource
    file = getsourcefile(object)
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/inspect.py", line 684, in getsourcefile
    filename = getfile(object)
  File "/h/hannes/anaconda3/envs/microexon-code-tf2/lib/python3.6/inspect.py", line 666, in getfile
    'function, traceback, frame, or code object'.format(object))
TypeError: None is not a module, class, method, function, traceback, frame, or code object

This is a problem for my (Jupyter-less) workflow as I like to use #%% in PyCharm to create run-able cells and send them to a shell with Ctrl+Enter. This way I can create my figures and do my analysis interactively and simply run the script at the end to obtain a rendered report. However, the error above throws a wrench into that workflow.

I think a workable simple solution would be for handout to simply do nothing when it detects an interactive shell.

I am just discovering this package but I wonder the feasibility of handout to support real time editing.

I was envisioning having integrations with editors such as Visual Studio Code, Sublime Text or Atom that would allow real time editing.

Your thoughts on this is much appreciated.

First of all, thanks for creating handout!

Is there any plan to integrate Jupyter and Handout files in the future?
I think the combination of both would help solve lots of issues current notebooks have, while keeping the practical approach jupyter notebooks have!

I think if we could have in Python something similar to how Rstudio implemented notebooks (where you can easily commit text files) while keeping the flexibility of working interactively it would be a game changer!

Thanks again for your work!

Html file title is currently is hardcoded Handout. A user might want to override it with custom title, something like "Jane's awesome notebook"

Implemetation would require small change in constructor as below:

class Handout(object):

  def __init__(self, directory, title="Handout"):

In a case when you can have several handouts the output folder may get cluttered. This may be a case when one wants to render several files and link them to display in a static site generator, eg via Github Pages.

I propose the html components/dependecies can be stored in a subfolder filename.html.files, which will make output folder cleaner.

This behavior is similar to how a browser, eg Chrome will save an html page to a local disk.

Is it possible to change the width of the page? Sometimes it's nice to plot figures side by side and use the wide monitors we have.

Right now, this requires the user to create a matplotlib figure with the image. There should be a doc.add_image(tensor_or_filename) method.

This would be useful for docstrings that should be rendered inside the code cell rather than interrupting the document with a Markdown cell. I'm not sure if there is a nice syntax for this so we might decide to not support it, but let's discuss!

Hi, is pathlib really a necessary dependency ? since: after install it gives:

    AttributeError: 'PosixPath' object has no attribute 'read_text'

can it be builted withou longdescription or with another text parser
? (it seems that pathlib has to do with windows and .Net)

This would be useful for docstrings that should be rendered inside the code cell rather than interrupting the document with a Markdown cell. I'm not sure if there is a nice syntax for this so we might decide to not support it, but let's discuss!

I'm thinking about porting Handout to Julia, this is also an exercise in understanding how Handout currently works.

Julia does not have classes, but rather data structures and bounded methods that operate on these structures. This calls for greater unbundling of data components and operations on them, compared to python.

My question to @danijar is to discuss/validate user scenarios and underlying functionality below.

Here is a user scenario:

• create Handout instance in script
• add user blocks (eg custom html, image, video) to handout instance with add_* functions
• make user blocks appear in a report with show() method or an optional show flag in add_* functions
• disqualify out parts of script from appearing in a report with #handout: exclude (single line), #handout: start-exclude, #handout: end-exclude (block of lines)
• view html report in browser with script contents and user-added blocks
• use other formats of report (eg. latex) to create new documents

Handout appears to be a data structure which holds the following:

• output directory path
• document title
• script path (may be useful to warn about calls to handout instance outside original script)
• stack of user blocks (pending and accepted blocks)
• counter for graphic files by type (image, video)

Methods that work with Handout:

• add_*() method creates local files for images and videos and adds content to internal report representation
• show() renders report with selected exporter(html, latex, markdow, ipynb) and saves it to output folder

In the background we need:

• a function that identifies code, text as well as comments in script source, creates source blocks and merges script source blocks with user blocks to produce internal representatinon of report
• functionality (a macro, in Julia) to trace line in script where a call was made
• renderer functions that take internal representation of report as blocks and produce output in report format (eg html or latex)
• possibly a writer that saves report content to local file

I think important design decision is saving local graphic files within add_*() functions. This can be taken away to a different layer (a queue of content by tupe of file), but would make things a bit less trasparent, unnecessary complicated.

Would be indebted to learn if I'm missing anything critical in a user scenario, data structures or background fucntions.

A tool or method to convert an .ipynb file into handout equivalent .py would be great.

While installing the package by pip, it does not install dependencies like 'matplotlib', 'imageio' etc. These have to be installed separately. We can make some changes to the 'setup.py' to include all dependencies so that it becomes very convenient to install the entire thing with just one command.