User guide with more usage examples and tips

[danijar]

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

[epogrebnyak]

My 5c on comparison to other project, perhaps very high level:

Probably need more workflows and selection creteria to distiguish workflows (goals a user tries to achieve, starting points IDE prefernces).

Important to aknwoledge there is no 'best' way, rather patterns of doing things in diffferent situations, with tradeoffs - not sure the charts reflects if as much now.

Some of my follow-up thoughts:

• I got a comment sweave/pweave/weave.jl family can be a separate block
• Types of markdown used in conversion help distinguish the tools
• latex/pdf workflow needs to be addressed in specific (as discussed in Exporting to LaTeX #18)

Is there something big I'm missing?

[danijar]

This looks great, thanks!

[danijar]

We can separate topics for the user guide in:

• When to use Handout
  • Typical user
  • Comparison to alternatives
• Specific usage examples
  • Report for data exploration
  • Training an ML model
  • Analyzing experiment metrics
  • Creating static web pages
  • Adding custom JS libraries
  • Converting to other formats

What do you think?

We can then start a draft in a Google doc or similar. The comparison to alternatives can be a flow chart or table. For the usage examples, code often speaks more than a thousand words. Once we've happy with it, we put it in the repo Wiki and also check the usage examples into the repository.

[epogrebnyak]

Maybe a markdown file in this repo in docs/README.md? Or a special branch and same file location if you want to keep master clean.

I also noticed the table in root README.md does not fit the screen on mobile/tablet, maybe you would want to change it. Last row in tabke consumes too much space.

[ugmurthy]

Adding a case to the above flowchart

• Require to publish a simple text report (includes figures almost nil code)
• I dont use R, nor do I use Jupyter
  then
• Handout is probably the go to place.

[epogrebnyak]

@ugmurthy - thanks for the workflow example. By saying "publish" fo you mean an html output?

[danijar]

@ugmurthy Please clarify a bit. For a simple text report, there is no need to use Python -- pure Markdown or Google docs are better suited. If you need figures and videos, Jupyter and Handout seem like good choices, depending on whether you prefer the Python programming workflow or Jupyter's interactive interpreter state. If you need non-Python code, Python Handout is not for you.

[ugmurthy]

@epogrebnyak Yes, by publish I mean html output.
@danijar "simple text report" : I probably used wrong words to describe but what i meant was. figures, images, video and text.
Example: I use python to process images, show my results as images and plots using matplotlib, very few animations. In the absence of handout I would save this in a file and then use Microsoft word to write a short report combining all the images,plots with some text to describe it - ZERO CODE.
I find this easy using handout the only pain point being, the #handout :exclude to the lines contain code. the begin-exclude and end-exclude would be really useful.

TIP: for generating PDF handouts with page-break where you need it.

• use doc.add_text('<p style="page-break-before: always">') for page-breaks
• use the browser to display report and then print to save-as-pdf to a file

[danijar]

To include styles and scripts from a URL:

doc.add_html('<link href="https://path/to/style.css" rel="stylesheet">')
doc.add_html('<script src="https://path/to/script.js"></script>')

To download and include them for offline viewing:

import wget  # pip3 install --user wget

wget.download(style_url, directory / 'style.css')
doc.add_html('<link href="style.css" rel="stylesheet">')

wget.download(script_url, directory / 'script.js')
doc.add_html('<script src="script.js"></script>')

[danijar]

To update the handout on script save (#36):

while inotifywait -e close_write script.py; do python3 script.py; done

[danijar]

I've started a more detailed comparison, to include in the README eventually:

Tool	Source code	Execution engine	Maintains state	Live updates	Developer interface	Output formats
Handout	Python files	Python interpreter	No	Yes	Text editor, Python IDE	HTML, PDF (LaTeX, Markdown, Notebook planned)
Jupyter	Notebook files	Jupyter	Yes	Yes	Web editor, Atom with Hydrogen, Visual Studio Code	HTML, LaTeX, PDF, Reveal JS, Markdown, ReStructuredText, Python
Knitr	R Markdown files with fenced Python blocks	R Studio	No	No	Text editor, R Studio	HTML, LaTeX, AsciiDoc, ReStructuredText
Pweave	Markdown with fenced Python blocks	Pweave	No	No	Text editor, Spyder, Hydrogen	HTML, LaTeX, Markdown, ReStructuredText

@epogrebnyak Can you think of other important design axes? Do you think the table is mostly correct?