From 866df253782b6b4fb02d2857feb4b203e29f6df5 Mon Sep 17 00:00:00 2001 From: Dan Goldsmith Date: Wed, 8 Jul 2020 08:44:14 +0100 Subject: [PATCH] Documentation structure reshuffle --- NOTES.md | 3 + docs/FAQ.md | 28 ------ docs/about/FAQ.md | 84 ++++++++++++++++++ docs/{ => about}/why.md | 21 +++-- docs/index.md | 7 +- docs/{ => userguide}/images/tutorial_cw_1.png | Bin docs/{ => userguide}/images/tutorial_cw_2.png | Bin docs/{ => userguide}/images/tutorial_cw_3.png | Bin docs/{ => userguide}/images/tutorial_cw_4.png | Bin docs/{ => userguide}/install.md | 0 docs/{ => userguide}/tutorial.md | 0 mkdocs.yml | 10 +-- 12 files changed, 105 insertions(+), 48 deletions(-) delete mode 100644 docs/FAQ.md create mode 100644 docs/about/FAQ.md rename docs/{ => about}/why.md (87%) rename docs/{ => userguide}/images/tutorial_cw_1.png (100%) rename docs/{ => userguide}/images/tutorial_cw_2.png (100%) rename docs/{ => userguide}/images/tutorial_cw_3.png (100%) rename docs/{ => userguide}/images/tutorial_cw_4.png (100%) rename docs/{ => userguide}/install.md (100%) rename docs/{ => userguide}/tutorial.md (100%) diff --git a/NOTES.md b/NOTES.md index c88aa2e..ead92b5 100644 --- 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 deleted file mode 100644 index 9c4d13f..0000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 - -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/about/FAQ.md b/docs/about/FAQ.md new file mode 100644 index 0000000..9c23a8d --- /dev/null +++ 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 + +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 b/docs/about/why.md similarity index 87% rename from docs/why.md rename to docs/about/why.md index 1af4427..0db3ffd 100644 --- a/docs/why.md +++ b/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 index 092519c..c045ae0 100644 --- 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 b/docs/userguide/images/tutorial_cw_1.png similarity index 100% rename from docs/images/tutorial_cw_1.png rename to docs/userguide/images/tutorial_cw_1.png diff --git a/docs/images/tutorial_cw_2.png b/docs/userguide/images/tutorial_cw_2.png similarity index 100% rename from docs/images/tutorial_cw_2.png rename to docs/userguide/images/tutorial_cw_2.png diff --git a/docs/images/tutorial_cw_3.png b/docs/userguide/images/tutorial_cw_3.png similarity index 100% rename from docs/images/tutorial_cw_3.png rename to docs/userguide/images/tutorial_cw_3.png diff --git a/docs/images/tutorial_cw_4.png b/docs/userguide/images/tutorial_cw_4.png similarity index 100% rename from docs/images/tutorial_cw_4.png rename to docs/userguide/images/tutorial_cw_4.png diff --git a/docs/install.md b/docs/userguide/install.md similarity index 100% rename from docs/install.md rename to docs/userguide/install.md diff --git a/docs/tutorial.md b/docs/userguide/tutorial.md similarity index 100% rename from docs/tutorial.md rename to docs/userguide/tutorial.md diff --git a/mkdocs.yml b/mkdocs.yml index 7fc77ec..c8adde0 100644 --- 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