From 5e8b217c8d32be4a6868466c2632286343229b45 Mon Sep 17 00:00:00 2001
From: Michael Currin <18750745+MichaelCurrin@users.noreply.github.com>
Date: Sat, 17 Oct 2020 16:23:20 +0200
Subject: [PATCH] docs: Update docs

---
 README.md                      |  2 +-
 docs/tutorial/installation.md  | 18 ++++-------------
 docs/tutorial/setup-project.md | 37 +++++++++++++++++++++++++++-------
 docs/tutorial/usage.md         | 18 +++++++++++------
 4 files changed, 47 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 10cba85..bad260d 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ This project uses the Read the Docs theme as seen above. It comes with MkDocs so
 - Easy to configure - see the short [mkdocs.yml](/mkdocs.yml) file.
 - Use the configured theme or switch to another - no need to write HTML and CSS yourself.
 - Each theme comes with a navbar and you write YAML - Jekyll themes on GH Pages need you to write your own HTML often and each theme handles navbar its own way (sometimes not at all).
-- Uses a deploy pipeline on GH Actions to deploy a GH Pages site.
+- Uses a deploy pipeline on GH Actions to deploy a GH Pages site - the action actually runs GH Pages deploy command.
 - The static site output is SEO-friendly.
 - Built on Python but you don't need to write any Python code.
 
diff --git a/docs/tutorial/installation.md b/docs/tutorial/installation.md
index ac85f8e..191d01a 100644
--- a/docs/tutorial/installation.md
+++ b/docs/tutorial/installation.md
@@ -30,31 +30,21 @@ For more info, see the [Installation](https://www.mkdocs.org/#installation) page
 Create a virtual environment at the project root.
 
 ```sh
-python3 -m venv venv
+$ python3 -m venv venv
 ```
 
 Activate it.
 
 ```sh
-source venv/bin/activate
+$ source venv/bin/activate
 ```
 
-Install dependencies using one of these approaches:
-
-<!-- Using `sh` for code block breaks for bullet points at least for read the docs theme. It looks like code can't go in bullet point after all.  -->
-
-Install directly.
+Install `mkdocs` from project dependencies list.
 
 ```sh
-pip install mkdocs
+$ pip install -r requirements.txt
 ```
 
-Create a `requirements.txt` file, add `mkdocs` to it then install from the file.
-
-```sh
-echo 'mkdocs' > requirements.txt
-pip install -r requirements.txt
-```
 
 ### Install globally
 
diff --git a/docs/tutorial/setup-project.md b/docs/tutorial/setup-project.md
index 15fac41..f55ab26 100644
--- a/docs/tutorial/setup-project.md
+++ b/docs/tutorial/setup-project.md
@@ -83,9 +83,7 @@ site/
 venv
 ```
 
-### Config
-
-#### Sample navbar
+### Navbar
 
 ```yaml
 nav:
@@ -93,19 +91,29 @@ nav:
     - About: about.md
 ```
 
-#### Sample theme
+### Themes
+
+#### Builtin
+
+Use a builtin theme that comes with MkDocs.
+
+The default.
 
-Use a builtin theme.
 ```yaml
 theme: mkdocs
 ```
-Or
+
+Using ReadTheDocs theme and alternative config syntax.
+
 ```yaml
-theme: readthedocs
+theme:
+  name: readthedocs
 ```
 
 Find more [supported themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). If it doesn't immediately, you'll have to use `pip` to install it and add to a `requirements.txt` file.
 
+#### ReadTheDocs Dropdown theme
+
 See below using [mkdocs-rtd-dropdown](https://github.com/cjsheets/mkdocs-rtd-dropdown).
 
 `requirements.txt`
@@ -118,3 +126,18 @@ mkdocs-rtd-dropdown
 theme:
   name: 'rtd-dropdown'
 ```
+
+### Material for MkdDocs theme
+
+See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Setup page for config options.
+
+`requirements.txt`
+```
+mkdocs-material-extensions>=1.0
+```
+
+`mkdocs.yml`
+```yaml
+theme:
+  name: 'material'
+```
diff --git a/docs/tutorial/usage.md b/docs/tutorial/usage.md
index d8e858e..f5564f8 100644
--- a/docs/tutorial/usage.md
+++ b/docs/tutorial/usage.md
@@ -9,24 +9,30 @@ _Note: If using VS Code, you can use the command palette instead to run the conf
 This will build the docs in memory (not to disk) and serve an auto-reloading server.
 
 ```sh
-mkdocs serve
+$ make serve
 ```
 
-Open URL:
+That will use `make` to run the following:
+
+```sh
+$ mkdocs serve --strict
+```
+
+Then open in your browser:
 
 - [localhost:8000](http://localhost:8000)
 
 
 ## Build docs
 
-Build docs site to `site` directory. Useful for production build or simulating that locally.
+Build docs site to `site` directory. This is useful for a CI flow.
 
 ```sh
-mkdocs build
+$ make docs
 ```
 
-Add this flag to build in strict mode.
+That will use `make` to run the following:
 
 ```sh
-mkdocs build --strict
+$ mkdocs build --strict
 ```