Package: rnmd
rnmd - markdown execution runtimeRNMD is a mardown execution runtime which can be used to run code contained inside of a markdown file.The vision behind it is to have your documentation and code together in one place and not maintain
2 versions of the same code (1 in .md and 1 script file).Especially useful when automatizing things under linux as it is easy to forget what some scripts were for,
if they do not contain documentation and maintaining the script and a good looking documentation would be too much effort.
(Especially with the very stripped down syntax of many command line programs this can become a problem)In that regardrnmdalso has installation features through which to manage these scripts make them optionally executable/runnable
from anywhere on the system. (mainly for automatization)It also adds features to easily transport your scripts and documentation to different machines.
Just make your markdown notebook a git repository and pull your commands to any machine.
Or just usernmdto run code of markdown files from an online url. (Easily share your code)Currentlysupported languagesare:bash scriptTODOS:Add specific block execution (--> makes it possible to run the samples in this readme)Support more languages (maybe add possibility to specify run command in markdown)Resolve module imports (To write whole programs using rnmd)Resolve paths (it they are for instance relative to the .md script)Improve argparse option handlingNamespaces and modules (prevent name conflicts by grouping documents and their backups)Multi Notebook managementWindows support (the proxies are right now bash on shell script and therefore not portable -> switch to python3)InstallationCan be easily installed from pypi with pip3.pip3installrnmdRunning from sourceYou can also alway clone the repo fromGitHuband run rnmd with python.python3rnmd.pynotebook/test.mdRunning code contained in a markdown fileExecute a markdown document using the rnmd markdown execution runtime.The document location passed to rnmd can currently be:A file pathAn url containing a documentrnmdnotebook/test.mdPassing arguments to the runtimernmdnotebook/test.md--argsarg1arg2arg3Note: If passing arguments to an installed proxy then the--argsflag is not required.Using rnmd to make a proxy linking to the specified documentProxies are itermediate bash scripts that link to the document to be run.(They also contain a shebang so you do not need to specify "bash" to run the script)By executing a proxy we are using rnmd to execute our linked document without having to write the command ourselves.#Make Proxyrnmdnotebook/test.md--proxyproxy/test#Run Proxyproxy/testSetting up rnmd for installation of proxiesYou can also use rnmd to install proxies to your system.To use the install feature of rnmd you need to run the setup process once before.During this process have to specify a location (yournotebook) where the proxies and document backups are installed to.After this you are asked if you want to add this location to your path (using your shell configuration) making your installed proxies
executable from anywhere on your system by its name.rnmd--setupInstalling proxiesInstall a proxy to your document on your system and make the command available from you path.(Requiresrnmd --setupto have been run)Also moves a backup copy of your document into your notbook, which can be executed if the main linked document was not found.#Make and install Proxyrnmdnotebook/test.md--installtest-proxy-install#Execute (if in path)test-proxy-installNote: Installing works for .sh scripts as well, so you can easily install them to your system.ProxiesProxies are currently bash scripts with a shebang for easy execution of a linked document using rnmd.
The however have other functions included as well:An included installer:
Ifrnmdis not yet installed the script asks the user if he wants to install it on the machine.
If yes was selectedrnmdis installed usingpip3Note: python3 and pip3 are requirements of rnmd.Running the backed up document instead, if the linked document could not be found (installed proxy only)Refreshing the document backup, from the linked docRunning the linked document usingrnmdMaking portable installsIf you want to transport your notebook to another machine you might want to perform a portable install of your documents instead.By doing this the document you are installing is moved to your notebook and the location inside of your notebook is linked by the proxy instead.The advantage of this is that you for instance can move you notebook around and to a different machine and the commands will all still work
as the documents stay inside of the notebook. (for example if you make your notebook a git repo)#Make and install Proxyrnmdnotebook/test.md--portableinstalltest-portable-proxy-install#Execute (if in path)test-portable-proxy-installList installed commands of your notebookrnmd--list
rnmd-lRemove/uninstall a command of your notebookrnmd--removetest-portable-proxy-installPrint the code contained inside of a documentrnmd--extractnotebook/test.mdCompile markdown to target locationrnmdnotebook/test.md--compilecompiled/testCreate backupsCreate a backup of the specified document in the backup dir of your notebook directory.rnmd--backupnotebook/test.mdCreate backups at locationCreate a backup of the specified document in the backup dir of your notebook directory."backupto" path can either be a file path or a directory into which to move the source document.Also useful for downloading documents to the local machine.rnmdnotebook/test.md--backuptotarget/test.mdCheck if the specified document existsrnmd--checknotebook/test.mdLicence notesThe choice for using LGPL 2.1 is strategic so if i may stop developing the runtime
it will still receive bugfixes/improvements from entities using this software in their programs.As you could build whole programs based on the rn_md runtime (markdown -> script) interpreter
the GPL licence is not the way to go as it probably would make those programs GPL as well,
which in turn hurts adoption of this project as it would pretty much restrict its
usage to GPL programs only.Because of these reasons the LGPL2.1 Licence was chosen.If you like the project consider dropping me a coffee