Documentation structure reshuffle

csx239 · Jul 8, 2020 · 866df253782b6b4fb02d2857feb4b203e29f6df5 · 866df25
1 parent 13d63c8
commit 866df253782b6b4fb02d2857feb4b203e29f6df5
Show file tree

Hide file tree

Showing 12 changed files with 105 additions and 48 deletions.
diff --git a/NOTES.md b/NOTES.md
@@ -119,8 +119,11 @@ docs$ mkdocs build
 
 #Preview 
 docs$ mkdocs serve
+
+upload mkdocs gh-deploy
 ~~~
 
+
 theme  mkdocs-material
 
 

diff --git a/docs/FAQ.md b/docs/FAQ.md
diff --git a/docs/about/FAQ.md b/docs/about/FAQ.md
@@ -0,0 +1,84 @@
+# FAQ
+
+## Why?
+
+Because I like to code my way around problems. See [Here](why.md) for a better explanation
+
+## Whats in a Name?
+
+Originally, Dans Markup Converter (DMC). 
+Yep, the chance to tell people to ```run DMC``` was too good to miss.
+However, including your name in something is a bit UMOA (Up My Own Arse).
+
+Anything that involves the full term *MarkDown*, seems to have
+negative connotation. As a general marking philosophy, it how well
+you have met the criteria, not penalising the making mistakes.
+marking down.
+
+  - You are ABLE to MARK things in MARKdown
+  - We can REuse templates.
+
+Backronyms are a good thing....
+
+
+
+## Do I have to do the whole Virtualenv thing.
+
+No. 
+
+If you are just using the software, its probably not necessary.
+Under some situations, it can also help us install things locally on
+windows, without needing admin permissions.
+
+
+However, If you are developing then it tends to be a very good idea
+though.  You only have to go through the hell of unmet dependencies
+when you move machines once, to see why. I suggest it so it becomes
+Muscle memory.
+
+
+The folks at Flask have a nice [discussion of the topic](https://flask.palletsprojects.com/en/0.12.x/installation/#virtualenv)
+
+
+## You know the Markdown parser is Insecure?
+
+Yep.  I know we can do some interesting things with the markdown
+render system, like XSS.
+
+However, So is Word / Excel / PDF etc., I can stick a Macro in a
+document that will P0wn your system.
+
+We are generating the docs we distribute, so we have control over what
+is put in them.  If it was a live system, where other people could add
+input, I wouldn't forget **RULE 1**
+
+
+## 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. 
+
+!!! note
+
+	I Had considered a web interface.  But that leads to a whole world of data govenance pain.
+	Perhaps one day we can write it as a Moodle (or Aula) plugin.
+
+
+There is no reason there cant be one, feel free put one together and 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/why.md → docs/about/why.md b/docs/why.md → docs/about/why.md
@@ -1,14 +1,17 @@
 # Why write this
 
-> NOTE: A lot of this is my own opinion (and may verge on a rant at
-> time). 
->
-> The "science" behind things like working efficiently can be
-> difficult. What works for one person, may not work for another.
-> Equally, things that drive one person mad, is the perfect way of
-> working for another.  As a veteran of the Emacs VS Vi "Holy War",
-> used to seeing two completely different philosophies on how to do
-> the same thing. 
+
+!!! note 
+
+	A lot of this is my own opinion (and may verge on a rant at
+	time). 
+
+	The "science" behind things like working efficiently can be
+	difficult. What works for one person, may not work for another.
+	Equally, things that drive one person mad, is the perfect way of
+	working for another.  As a veteran of the Emacs VS Vi "Holy War",
+	used to seeing two completely different philosophies on how to do
+	the same thing. 
 
 Currently in Note form.  I will come back and fix when I have time.
 

diff --git a/docs/index.md b/docs/index.md
@@ -5,7 +5,7 @@ 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)
+You can read my rationale for developing it [here](about/why.md)
 
 
 There is currently a generic feedback template, and a template based on
@@ -28,11 +28,6 @@ All the requirements should be in the standard uni image.
 All the code uses native python packages, so there should be no need
 to install any other software.
 
-# Documentation
-
- - [Installation](install.md)
- - [Tutorial](tutorial.md)
-
 
 # Improvements and Contributing
 

diff --git a/docs/images/tutorial_cw_1.png → docs/userguide/images/tutorial_cw_1.png b/docs/images/tutorial_cw_1.png → docs/userguide/images/tutorial_cw_1.png
diff --git a/docs/images/tutorial_cw_2.png → docs/userguide/images/tutorial_cw_2.png b/docs/images/tutorial_cw_2.png → docs/userguide/images/tutorial_cw_2.png
diff --git a/docs/images/tutorial_cw_3.png → docs/userguide/images/tutorial_cw_3.png b/docs/images/tutorial_cw_3.png → docs/userguide/images/tutorial_cw_3.png
diff --git a/docs/images/tutorial_cw_4.png → docs/userguide/images/tutorial_cw_4.png b/docs/images/tutorial_cw_4.png → docs/userguide/images/tutorial_cw_4.png
diff --git a/docs/install.md → docs/userguide/install.md b/docs/install.md → docs/userguide/install.md
diff --git a/docs/tutorial.md → docs/userguide/tutorial.md b/docs/tutorial.md → docs/userguide/tutorial.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,9 +19,9 @@ repo_url: https://github.coventry.ac.uk/aa9863/reMarkAble
 
 nav:
   - Home: index.md
-  - Documentation:
-    - Installation: install.md
-    - Getting Started:  tutorial.md
+  - User Guide:
+    - Installation: userguide/install.md
+    - Getting Started:  userguide/tutorial.md
   - About:
-    - Why: why.md
-    - FAQ: FAQ.md
+    - Why: about/why.md
+    - FAQ: about/FAQ.md