#Jupyter-like program you use with external editor

For making documents or "sketches" for programming. In Python, for instance, the comment sections are interpreted as (defaultly markdown) text, and the Python is evaluated.

Like Jupyter, it's a local server which run

Unlike Jupyter, you edit the code in an external editor. Perhaps in the future I'll add settings to do it, but 1) editing in the browser can be annoying, 2) i want to actually make it work without a browser, eventually. Also unlike Jupyter does not yet have buttons to run code, instead it just runs everything, and re-does the needed things when the files change. The things that take long should already be in a threading wrapper. They'll update their part of the page when done.

It should be very extensible; Python modules in live_doc.interpreters.* are used to interpret input text from different formats/programming languages. A few of them use the subprocess module to call on other programs. Currently hevea is used for LaTeX, for example. Configuration can select what interpreter to use, as well as fallbacks when those don't work.

Configuration also selects wrappers and code highlighters the same way. Wrappers achieve different features like threading, remembering previous state, displaying the code section and the result.

#Features (some recap)

• NOTE: the level of testing right now isn't great. There may be bugs.

• It updates as soon as the file changes.

• In runs a local server.

  • TODO add other non-local server options. (like gtk)

• Quite separately, interpreters, wrappers and highlighters can be written.

  • They can be selected with configuration, configuration can also do fallbacks.

  • The Python one already automatically interprets some Python types like plots.

  • TODO specify how to write these interpreters.

• Layered configuration and asset files.

• Saving to .html and/or .zip with the output files in it. (TODO suppose may want input ones too?)

• Server NOT intended to face public networks. It has basic cookie authentication, but for defense in deph. (Also you edit using your own editor, shouldn't be possible to do arbitrary things via http-calling the server right now.)

• TODO document the code.

#Current interpreters:

• Python-in-a-subprocess. A subprocess was needed to get stdout/stderr properly.

  • An advantage is you can change the python program call.(perhaps even run in firejail or bwrap?)

• Hevea for LaTeX. (seems ok but far from perfect)

• Graphviz for interpreting .dot files.

• sh for shell script files. TODO should just add zsh etc.

#Install

It always needs:

• It's written in Python, so will always need that.
• inotifywait is used to wait for a file to change.

In practice right now, also needs these:

• It's tested with the discount markdown program.
• bat is defaultly used to "terminal" syntax highlight. (vimcat may also work)
• aha is used to turn that into html syntax highlighting.

Hopefully in the future i'll add more options (& be confident they'll all work? Hmm)

It has some path & sys.path changing so that you can just run the file bin/live_doc, it has some logic in there so it works even if you symlink to the program.

It should also work if you symlink the live_doc/ direction in here from ~/.local/lib/python$PY_VERSION/site-packages/, however, this project is not really intended for use as library.

#Usage

bin/live_doc -serve  # Should run a server. Files relative to `pwd`.

Then open a markdown file.. for instance the one in localhost:4000/try/test.md assuming it is running from this projects directory. (try editing test.md)

It has a --help. Not much configuration otherwise. The files in assets/ are simple enough to edit. (in future ~/.config, /etc/ etcetera.)

#Suggested vim setup for markdown:

Using python-with-stuff-embedded as main format, and have markdown in the comments may work better. For vims you can use JEDI then, at least.

However can also use markdown-with-stuff-embedded, advantage there is that you can get syntax highlighting for markdown and contents of files: https://vimtricks.com/p/highlight-syntax-inside-markdown/

let g:markdown_fenced_languages = ['html', 'python', 'ruby', 'vim']
let g:vim_markdown_conceal = 0
let g:vim_markdown_conceal_code_blocks = 0

#License: AGPL 3.0

See doc/agpl-3.0.txt