Added rough documentation for code_from_file and placeholders for t…

…he rest

README.md

@@ -1 +1,103 @@
 # mk_doc_ultra
+
+A collection of macros to help write tutorials.
+
+# Usage
+
+You can download the contents or add it as a submodule to your repo.
+
+For the rest of this document we assume it is located in the same place as your `mkdocs.yaml` file. That is, in the root of the repo, in a directory called `mk_doc_ultra`.
+
+Add the following to your `plugins/macros` config hierarchy:
+
+```
+module_name: 'mk_doc_ultra.main'
+include_dir: 'mk_doc_ultra/'
+```
+
+For example:
+```
+plugins:
+  - search
+  - macros:
+      module_name: 'mk_doc_ultra.main'
+      include_dir: 'mk_doc_ultra/'
+
+```
+
+Then in the `theme` element, add `custom_dir: 'mk_doc_ultra/'`.
+
+Finally, include `mk_ultra.css` in your `extra_css` config.
+
+A full example:
+
+```
+site_name: Some Site
+
+nav:
+  - home: index.md
+
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      linenums: false
+
+plugins:
+  - search
+  - macros:
+      module_name: 'mk_doc_ultra.main'
+      include_dir: 'mk_doc_ultra/'
+
+
+theme: 
+  name: material
+  custom_dir: 'mk_doc_ultra/'
+  logo: 'images/logo.svg'
+  palette:
+    primary: 'indigo'
+    accent: 'indigo'
+    
+extra:
+  draft: 1
+  year: '2020/21'
+
+extra_css: 
+    - css/extra.css
+    - mk_ultra.css
+
+```
+
+
+The `extra` variables shown above are used by the `version_info` macro.
+
+
+## Provided Macros
+
+### version_info
+### todo
+### button
+
+Adds a button. Taken from the sample macro file and left because it might be useful later.
+
+### state
+### code_from_file
+
+Adds a code block taken from the given file.
+Example:
+
+```
+{{code_from_file("example.py")}}
+```
+
+Parameters:
+ - start: If given, sets the starting line number to show. Defaults to 0
+ - stop: If given, sets the last line number to show. Defaults to the last in the file
+ - flavour: sets the type of highlighting to be used, e.g. "python"
+ - download: If set to True, includes a link to download the source file. Default is False
+ - execute: If set to true, executes the code and displays the output
+ - typed: If given, this string will be used as user input to the code being executed
+ - colour: If set to true, adds output highlighting. Curerntly only highlights the piped user input
+
+
+### external_markdown