Merge pull request aa9863#16 from aa9863/Documentation

Documentation
csx239 · Jul 5, 2020 · d1b7dcca543680f8ed26af412e977a1ab285ee4f · d1b7dcc
2 parents 4486247 + 28f2931
commit d1b7dcca543680f8ed26af412e977a1ab285ee4f
Show file tree

Hide file tree

Showing 12 changed files with 501 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -113,3 +113,32 @@ Paths / Organisation for the Templates  do it
 
 The second is better for orgnaisation,  but a makes the command line clunky.
 We could map in the main function though...
+
+
+## Documentation
+
+Can be found <here>
+
+Generated with MKDocs
+
+To regenerate the docs 
+
+~~~
+#Install
+$pip install mkdocs
+
+#Build (in the docs directory)
+docs$ mkdocs build
+
+#Preview 
+docs$ mkdocs serve
+~~~
+
+theme  mkdocs-material
+
+
+https://squidfunk.github.io/mkdocs-material/extensions/pymdown/
+
+And a really useful set of extenstions
+
+https://facelessuser.github.io/pymdown-extensions/
diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,6 @@
+#TODO List
+
+ - Windows specific version of the Guide
+ - Images in the Guide
+ - Update Links to Course code Location
+ - Once we have a proper projet name (I think reMarkAble) let keep it.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -0,0 +1,28 @@
+# FAQ
+
+## Why?
+
+Because I like to code my way around problems. See [Here](why.md) for a better explanation
+
+## Why the command line?
+
+Simple answer, I don't like writing GUI's. Also typing a few commands
+seems much more efficient than lots of clicking too. 
+
+There is no reason there cant be one, feel free to submit a pull
+request.
+
+## Why Markdown, and not <Insert Template language here>
+
+A few reasons. 
+
+  1. I teach in computing, and encourage the students to use GitHub,
+     which will render Markdown nicely in the web interface.  It
+     seemed like a good idea to reinforce this good practice.
+  1. Its got a nice clean syntax, and as text can be edited on just about anything.
+  1. It has support for things like Maths, and Code.
+
+## Pink Lady Mode?
+
+I Like Puns, I Like obscure movie references, (I don't particularly
+like the movie).  And it seemed to fit.
diff --git a/docs/images/tutorial_cw_1.png b/docs/images/tutorial_cw_1.png
diff --git a/docs/images/tutorial_cw_2.png b/docs/images/tutorial_cw_2.png
diff --git a/docs/images/tutorial_cw_3.png b/docs/images/tutorial_cw_3.png
diff --git a/docs/images/tutorial_cw_4.png b/docs/images/tutorial_cw_4.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,66 @@
+# reMarkAble Markdown Marking
+
+This project allows us to generate documents such as Coursework
+Briefs, or Feedback using markdown.  I find it a much nicer way of
+working, and the generated docs should be more consistent for the
+students.
+
+You can read my rationale for developing it [here](why.md)
+
+
+There is currently a generic feedback template, and a template based on
+the EEC coursework brief document.
+
+!!! note
+
+    The coursework Brief is a WIP.  While the method to generate will
+    stay the same, the look and feel will certainly change (when I get
+    some UX time)
+
+## Requirements
+
+All the requirements should be in the standard uni image.
+
+  - Web Browser
+  - Text Editor
+  - Python (3.x preferred)
+
+All the code uses native python packages, so there should be no need
+to install any other software.
+
+
+# Documentation
+
+ - [x] [Installation](install.md)
+ - [x] [Tutorial](tutorial.md)
+ - [ ] Coursework Guide walkthrough
+ - [ ] Writing your own templates
+ - [ ] Markdown Cheat Sheet.
+
+
+# Improvements
+
+## Bugs or Undocumented Features?
+
+Are to be expected,  been cobbling this together in my weekends.
+
+There is an [Issue tracker](https://github.coventry.ac.uk/aa9863/reMarkAble/issues)
+please use it.
+
+
+## Contributing
+
+If you have any:
+
+  - Ideas for improvement / Feature Requests
+  - New Templates
+  - Code contributions 
+
+You are welcome to contribute to the project. The more people who use
+it the better.
+
+Either get in touch, submit and issue, or a pull request with your changes.
+
+
+
+
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,95 @@
+# Installation
+
+Get a copy of the source code from the 
+[GithubRepo](https://github.coventry.ac.uk/aa9863/reMarkAble) It doesn't
+matter if you clone the repository or get the zip file.
+
+If using git you can clone the repo with
+
+```
+dang@dang-laptop ~/Github$ git clone git@github.coventry.ac.uk:aa9863/reMarkAble.git
+Cloning into 'reMarkAble'...
+remote: Enumerating objects: 375, done.
+remote: Counting objects: 100% (375/375), done.
+remote: Compressing objects: 100% (208/208), done.
+remote: Total 697 (delta 223), reused 303 (delta 161), pack-reused 322
+Receiving objects: 100% (697/697), 107.59 KiB | 95.00 KiB/s, done.
+Resolving deltas: 100% (407/407), done.
+```
+
+Once you have the code navigate to its location using the command line.
+
+```
+dang@dang-laptop ~/Github$ cd reMarkAble
+dang@dang-laptop ~/Github/reMarkAble$
+```
+
+
+!!! tip "Installation in a virtual environment"
+
+	Virtual environments (venv) give us a way of sandboxing python software we
+	install.  It means that they are not installed in the global path.
+	Personally, as a developer, I prefer this as it means I don't get caught out by
+	dependencies or clutter up my Python name space with cruft.
+
+	We can create a venv using
+
+	```bash
+	dang@dang-laptop ~/Github/reMarkAble$ python -m venv env
+	```
+
+	```bash
+	dang@dang-laptop ~/Github/reMarkAble$ source env/bin/activate
+	```
+
+	Each time we want to use the code we need to access enter the virtual environment.
+	We can do this in Linux / mac with
+
+	```bash
+	(env) dang@dang-laptop ~/Github/reMarkAble$
+	```
+
+	or Windows
+	```
+	C:\> env\Scripts\activate.bat
+	```
+
+## Installing 
+
+We can now install the program using the setup script.
+
+
+```bash
+(env) dang@dang-laptop ~/Github/reMarkAble$ python setup.py install
+running install
+running bdist_egg
+running egg_info
+
+... <SNIP> ...
+
+```
+
+## Optional:  Run the Unit-tests
+
+```
+$ python setup.py test
+running pytest
+
+... <SNIP> ...
+====================== test session starts ======================
+platform linux -- Python 3.8.3, pytest-5.4.3, py-1.9.0, pluggy-0.13.1
+rootdir: /home/dang/Github/reMarkAble
+collected 66 items                                              
+
+test/test_controller.py ......                            [  9%]
+test/test_markdown.py ........................            [ 45%]
+test/test_parser.py ...............                       [ 68%]
+test/test_render.py ...........                           [ 84%]
+test/test_sections.py ..........                          [100%]
+
+====================== 66 passed in 0.29s =======================
+(env) dang@dang-laptop ~/Github/reMarkAble$           ✹ ✭master 
+```
+
+If any tests fail, drop me a message so I can try to work out what has
+happened.