Updating Docs for commit 3f4afba made on 2023-12-30T12:34:03+00:00 fr…

…om refs/heads/master by michaelb

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 92ff66bc006609b29d0772e8d9dab65d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

README.md

@@ -0,0 +1,7 @@
+# README for the GitHub Pages Branch
+This branch is simply a cache for the website served from https://michaelb.github.io/sniprun,
+and is  not intended to be viewed on github.com.
+
+For more information on how this site is built using Sphinx, Read the Docs, and GitHub Actions/Pages, see:
+ * https://www.docslikecode.com/articles/github-pages-python-sphinx/
+ * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1

_sources/index.rst.txt

@@ -0,0 +1,28 @@
+.. Sniprun documentation master file, created by
+   sphinx-quickstart on Sun Oct  9 14:55:25 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Sniprun's documentation!
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Sniprun:
+
+   sources/README.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Display modes:
+
+   sources/display_modes.md
+
+.. toctree::
+   :maxdepth: 1
+   :hidden: 
+   :caption: Interpreters:
+
+
+   sources/common_options.md
+   sources/interpreters/*.md

_sources/sources/common_options.md.txt

@@ -0,0 +1,122 @@
+## Interpreter configuration
+
+You can select an interpreter (with its name from `:SnipInfo`) if several of them support the language/filetype
+(see {ref}`use_on_filetype <use-on-filetype>` if necessary) and you want a specific one
+
+```
+lua << EOF
+require'sniprun'.setup({
+    selected_interpreters = { "Some_interpreter", "Python3_fifo"},
+})
+EOF
+```
+
+Many interpreters have REPL capabilities that are _not_ enabled by default. You can turn this behavior on (or off) with the `repl_enable` and `repl_disable` keys, that similarly take interpreters names as arguments:
+
+
+```
+lua << EOF
+require'sniprun'.setup({
+    repl_enable = {"Python3_original", "Julia_jupyter"},   --# enable REPL-like behavior for the given interpreters
+    repl_disable = {"Lua_nvim"},          --# disable REPL-like behavior for the given interpreters
+})
+EOF
+```
+
+
+## Common options
+
+Every interpreter supports getting documentation via `:SnipInfo <interpreter_name>`
+
+To specify interpreter options, you have to add the following to your sniprun config:
+
+
+
+```
+lua <<EOF
+require('sniprun').setup({
+
+    interpreter_options = {
+        <Interpreter_name> = {
+            some_specific_option = value,
+            some_other_option = other_value,
+        }
+    }
+  }, 
+})
+EOF
+```
+
+For example:
+
+```
+lua <<EOF
+require('sniprun').setup({
+
+    interpreter_options = {         --# interpreter-specific options, see doc / :SnipInfo <name>
+
+        --# use the interpreter name as key
+        GFM_original = {
+            use_on_filetypes = {"markdown.pandoc"}    --# the 'use_on_filetypes' configuration key is
+                                                      --# available for every interpreter
+        },
+        Python3_original = {
+            error_truncate = "auto"         --# Truncate runtime errors 'long', 'short' or 'auto'
+                                            --# the hint is available for every interpreter
+                                            --# but may not be always respected
+        }
+  }, 
+})
+EOF
+```
+
+(use-on-filetype)=
+### The "use_on_filetypes" key
+
+The `use_on_filetypes` key is implicitely an option of every interpreter
+
+```
+interpreter_options = {
+    GFM_original = {
+        use_on_filetypes = {"markdown.pandoc", "rstudio" }
+    }
+}
+```
+
+### The "error_truncate" key
+
+Also available for every interpreter if you don't like how sniprun truncate some outputs by default (auto), but it will not have an effect on all interpreters.
+
+```
+interpreter_options = {
+    Python3_original = {
+        error_truncate = "auto"     --# Truncate runtime errors 'long', 'short' or 'auto'
+    }
+}, 
+```
+
+## The interpreter/compiler keys
+
+Almost every interpreter support either the "interpreter" or "compiler" key even if not explicitely documented, depending on whether they're about an interpreter or compiled language.
+
+example:
+
+```
+interpreter_options = {
+    Python3_original = {
+        interpreter = "python3.9"
+    }
+    Rust_original = {
+        compiler = "/home/user/bin/rustc-patched"
+    }
+}, 
+```
+
+You can see what interpreters/compilers are being used at any time by watching sniprun's log for the line
+"using compiler XXXX" or "using interpreter XXXX" when you run a snippet.
+
+Exceptions:
+ - Scala_original has both interpreter and compiler keys that should be set consistently with each other
+ - *_jupyter, Generic, GFM_original, Orgmode_original, and Neorg_original do not support any of these keys
+
+

_sources/sources/display_modes.md.txt

@@ -0,0 +1,222 @@
+# Introduction
+
+Sniprun has many different display modes, which you can combine and filter:
+
+Display modes:
+
+- "Classic"
+- "VirtualText"
+- "Terminal"
+- "TerminalWithCode"
+- "TempFloatingWindow"
+- "LongTempFloatingWindow"
+- "NvimNotify"
+- "Api"
+
+Suffixes:
+
+- "Ok" (only display sucessfull results)
+- "Err" (only display errors - compilation or runtime)
+
+To configure which display mode(s) you want, just include their names (+suffix if wanted) in the `display` configuration key:
+
+```
+lua << EOF
+
+require('sniprun').setup({
+    display = {
+        "Classic",         -- will display both 'ok' & 'err' results in the command area
+        "VirtualTextOk",   -- will display only 'ok' results as virtual text on the line sent to sniprun
+    },
+})
+
+EOF
+```
+
+# Available display modes
+
+(classic-display)=
+## Classic
+
+Results are displayed on the command area.
+
+**Pro/cons:**
+
+ - Supports multi-lines results
+ - Can (maybe) be copied
+ - Ok/Err highlighting
+ - Disappear on the next keypress
+
+```
+lua << EOF
+require'sniprun'.setup({
+  display = { "Classic" },
+})
+EOF
+```
+
+
+![](../../ressources/visual_assets/classic.png) 
+
+
+
+(virtualtext-display)=
+## Virtual Text
+
+Results are displayed as virtual text after the end of the line you sent to sniprun. (In case it's a block, it goes at the end of the last line)
+
+**Pro/cons:**
+
+ - Does not disappear (except after a SnipClose)
+ - Ok/Err highlighting (outputs for ok and error results are highlighted with the groups `SniprunVirtualTextOk` and `SniprunVirtualTextErr` respectively)
+ - Visually close to the code
+ - No multiline possible. Results are shortened on a best-effort basis
+ - Cannot be copied
+
+```
+lua <<EOF
+require'sniprun'.setup({
+  display = {
+    "VirtualText",
+  },
+})
+EOF
+```
+
+ ![](../../ressources/visual_assets/virtual_text.png)
+
+
+(floatingwindow-display)=
+## Temporary floating windows
+
+Result are displayed in (temporary) floating windows. "LongTempFloatingWindow" will only display multiline messages, which allow for nice combinations with "VirtualText"
+
+**Pro/cons:**
+
+ - Visually close to the code
+ - Ok/Err highlighting (the highlight groups used are "SniprunFloatingWinOk" and "SniprunFloatingWinErr")
+ - Supports multiline results
+ - Disappears on the next keypress
+ - Cannot be copied
+
+```
+require'sniprun'.setup({
+  display = { "TempFloatingWindow" },
+})
+```
+
+![](../../ressources/visual_assets/floating_window.png) 
+
+(terminal-display)=
+## Terminal
+
+Results are displayed in a side panel
+
+**Pro/cons:**
+
+ - Support multiline, and auto-scrolls when full
+ - Results can be copied and do not disappear (except after a SnipClose)
+ - Customizable width
+ - No highlighting (only a 'ok' or 'err' message)
+ - Can display the code that ran along with the result (with the "TerminalWithCode" variant)
+
+```
+lua << EOF
+require'sniprun'.setup({
+    display = { "Terminal" },
+    display_options = {
+        terminal_scrollback = vim.o.scrollback, -- change terminal display scrollback lines
+        terminal_line_number = false, -- whether show line number in terminal window
+        terminal_signcolumn = false, -- whether show signcolumn in terminal window
+        terminal_position = "vertical", --# or "horizontal", to open as horizontal split instead of vertical split
+        terminal_width = 45,          --# change the terminal display option width (if vertical)
+        terminal_height = 20,         --# change the terminal display option height (if horizontal)
+    },
+})
+EOF
+```
+
+
+if you experience wrapping of the header line '---- OK ---' due to the presence of a number column, you can (and should anyway) set 
+
+```vim
+autocmd TermOpen * setlocal nonu
+```
+
+
+![](../../ressources/visual_assets/terminal.png)
+![](../../ressources/visual_assets/terminalWithCode.png)
+
+
+(notification-display)=
+## Notification
+
+Results are displayed through the [nvim-notify](https://github.com/rcarriga/nvim-notify) plugin (which must be installed).
+
+**Pro/cons**:
+
+ - Supports multiline
+ - Ok/Err highlighting
+ - Disappears after 5s (timeout is customisable)
+
+
+ ```
+lua << EOF
+require'sniprun'.setup({
+    display = {"NvimNotify"},
+    display_options = {
+        notification_timeout = 5   -- in seconds
+    },
+})
+EOF
+```
+
+![](../../ressources/visual_assets/nvimnotify.png) 
+
+(api-display)=
+## API display
+
+Results are displayed through an user-provided function
+
+You can register listeners that will be called upon (async) sniprun output:
+
+
+```lua
+local sa = require('sniprun.api')
+
+sa.register_listener(custom_function)
+```
+
+where custom function is a function that take one unique argument: a table which contains at least two entries:
+
+ - 'status' (a string that's either 'ok' or 'error' for now, but your function should accept & manage other values)
+ - 'message' (also a string, maybe be multiline)
+
+(Simply put, registered functions are callbacks)
+
+
+Thus, an example of such a function (imitating the 'Classic' display with 'uwu' tendencies) would be
+
+```lua
+local api_listener = function (d)
+    if d.status == 'ok' then
+        print("Nice uwu: ", d.message)
+    elseif d.status == 'error' then
+        print("Oh nyow! Somethuwuing went wyong: ", d.message)
+    else 
+        print("Whut is this myeow? I don't knyow this status type nyah")
+    end
+end
+
+sa.register_listener(api_listener)
+```
+
+(You must also enable the 'Api' display option, and in this particular case where things are printed to the command line area, disabling 'Classic' is recommended)
+
+
+If your function requires to be manually closed (on `SnipClose`), you can register a closer the same way:
+
+```lua
+sa.register_closer(custom_function)
+```
+

_sources/sources/interpreters/Ada_original.md.txt

@@ -0,0 +1,11 @@
+## Ada original
+
+
+dependencies: Need gcc-ada and gnatmake
+
+
+Note: because Ada needs variables to be declared before the begin (in a non contiguous section of the file), SnipRun is not very useful here and will, in practice, only be able to run blocs like
+
+```
+Put_Line("raw text");
+```