Switch our documentation to mkdocs material (#42)

* initial version of docs using mkdocs material

* tweak the visual look

* CSS tweaks

* remove _summar

* font tweak

* update README to reflect mkdocs

* workflows to update documentation

* add site to .gitignore

.github/workflows/devel_docs.yml

@@ -0,0 +1,28 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Update Develop Docs
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  devel_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.7'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel 
+        pip install -r requirements-release.txt
+    - name: Update docs
+      run: |
+        ./release_docs devel

.github/workflows/python-publish.yml

@@ -26,7 +26,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install setuptools wheel 
-        pip install -r requirements.txt
         pip install -r requirements-release.txt
     - name: Configure git
       run: |
@@ -56,3 +55,6 @@ jobs:
       run: |
         python setup.py sdist bdist_wheel
         twine upload dist/*
+    - name: Update docs
+      run: |
+        ./release_docs latest

.gitignore

@@ -6,3 +6,5 @@ build
 dist
 milc.egg-info
 .idea
+venv
+site

README.md

@@ -125,7 +125,7 @@ Please follow this checklist before submitting a PR:
 
 * [ ] Format your code: `yapf -i -r .`
 * [ ] Generate docs: `./generate_docs`
-* [ ] Add any new doc files to `docs/_summary.md`
+* [ ] Add any new doc files to the `nav` section of `mkdocs.yml`
 * [ ] Run tests: `./ci_tests`
 
 # FAQ

ci_tests

@@ -37,7 +37,7 @@ def main(cli):
         build_ok = False
 
     cli.log.info('Running yapf...')
-    cmd = ['yapf', '-q', '-r', '.']
+    cmd = ['yapf', '-q', '-r', '--exclude', 'venv/**', '.']
     result = run(cmd, stdin=DEVNULL)
     if result.returncode != 0:
         build_ok = False

docs/_summary.md

@@ -1,27 +0,0 @@
-* [Home](README.md)
-* [Breaking Changes](breaking_changes.md)
-* [Installation](installation.md)
-* [Tutorial](tutorial.md)
-* Features
-    * [ANSI Color](ANSI.md)
-    * [Argument (Tab) Completion](argcomplete.md)
-    * [Argument Parsing](argument_parsing.md)
-    * [Configuration](configuration.md)
-    * [Config Subcommand](subcommand_config.md)
-    * [Logging](logging.md)
-    * [Metadata](metadata.md)
-    * [Sparklines](sparklines.md)
-    * [Spinners](spinners.md)
-    * [Subprocesses](subprocesses.md)
-    * [Thread Safety](threading.md)
-    * [User Input](api_questions.md)
-<!-- DO NOT ADD OR CHANGE ANYTHING BELOW THIS LINE UNLESS `generate-docs` CREATED NEW FILES -->
-* API Reference
-    * [milc.ansi](api_ansi.md)
-    * [milc.attrdict](api_attrdict.md)
-    * [milc.configuration](api_configuration.md)
-    * [milc.emoji](api_emoji.md)
-    * [milc.milc](api_milc.md)
-    * [milc.questions](api_questions.md)
-    * [milc.sparkline](api__sparkline.md)
-    * [milc.subcommand.config](api_subcommand_config.md)

docs/api_questions.md

@@ -81,5 +81,6 @@ Users can enter either the number or the text of their choice. This will return
 
 Users can enter either the number or the text of their choice.
 
-!> This will return the value of the item they choose, not the numerical index.
+!!! warning
+    This will return the value of the item they choose, not the numerical index.
 

docs/metadata.md

@@ -12,7 +12,8 @@ from milc import cli
 
 You should only do this once, and you should do it as early in your program's execution as possible.
 
-!> Do not import `set_metadata` and `cli` at the same time! When you run `set_metadata` the `cli` object will be replaced, but your existing import will continue to reference the old `cli` object.
+!!! danger
+    Do not import `set_metadata` and `cli` at the same time! When you run `set_metadata` the `cli` object will be replaced, but your existing import will continue to reference the old `cli` object.
 
 ## Environment based setup
 

docs/stylesheets/milc.css

@@ -0,0 +1,11 @@
+.md-nav__list {
+    padding-left: 0.5rem;
+}
+
+.md-grid {
+  max-width: initial;
+}
+
+.md-footer {
+  display: none;
+}

docs/tutorial.md

@@ -234,22 +234,22 @@ Now that we've written our program and we have a better idea what is going
 on, let's explore how it works. We'll start by demonstrating it with no
 arguments passed.
 
-![Simple Output](https://i.imgur.com/Ms3G8Aw.png)
+![Simple Output](images/tutorial_example1.png)
 
 We'll demonstrate entering a subcommand here:
 
-![Hello Output](https://i.imgur.com/a9RjE8S.png)
+![Hello Output](images/tutorial_example2.png)
 
 So far so good. Now let's take a look at the help output:
 
-![Help Output](https://i.imgur.com/MR5TbHv.png)
+![Help Output](images/tutorial_example3.png)
 
 Finally, let's combine it all together to demonstrate the use of both
 general and subcommand flags:
 
-![Flag Output](https://i.imgur.com/0aGFcKc.png)
+![Flag Output](images/tutorial_example4.png)
 
-# Doing More
+## Doing More
 
 Our program does a lot in only a few lines, but there's a lot more you can
 do. Explore the rest of the documentation to see everything MILC can do.

generate_docs

@@ -46,18 +46,6 @@ def main(cli):
         doc_file = doc_path / filename
         doc_file.write_text(result.stdout)
 
-    # Rebuild _summary.md
-    summary_file = doc_path / '_summary.md'
-    summary_text = summary_file.read_text(encoding='utf-8')
-    summary_end = summary_text.index(summary_demarc)
-    new_summary = [
-        summary_text[:summary_end],
-        summary_demarc,
-    ]
-
-    for module, doc_file in sorted(doc_files):
-        new_summary.append(f"    * [{module}]({doc_file})")
-
     if cli.args.commit:
         cli.run(['git', 'add', 'docs'], capture_output=False)
         cli.run(['git', 'commit', '-m', '[ci] Updated API documentation'], capture_output=False)

milc/questions.py

@@ -156,7 +156,8 @@ def choice(heading, options, *args, default=None, confirm=False, prompt='Please
 
     Users can enter either the number or the text of their choice.
 
-    !> This will return the value of the item they choose, not the numerical index.
+    !!! warning
+        This will return the value of the item they choose, not the numerical index.
     """
     if not args and kwargs:
         args = kwargs

mkdocs.yml

@@ -0,0 +1,91 @@
+extra_css:
+  - stylesheets/milc.css
+extra:
+  version:
+    provider: mike
+markdown_extensions:
+  - admonition
+  - codehilite:
+      guess_lang: false
+  - def_list
+  - fenced_code
+  - footnotes
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.keys
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.tasklist
+  - pymdownx.tilde
+  - sane_lists
+  - tables
+  - toc:
+      marker: ''
+      permalink: true
+      toc_depth: 3
+  - wikilinks
+nav:
+  - Home: README.md
+  - Breaking Changes: breaking_changes.md
+  - Installation: installation.md
+  - Tutorial: tutorial.md
+  - Features:
+    - ANSI: ANSI.md
+    - Argument (Tab) Completion: argcomplete.md
+    - Argument Parsing: argument_parsing.md
+    - Configuration: configuration.md
+    - Config Subcommand: subcommand_config.md
+    - Logging: logging.md
+    - Metadata: metadata.md
+    - Sparklines: sparklines.md
+    - Spinners: spinners.md
+    - Subprocesses: subprocesses.md
+    - Thread Safety: threading.md
+    - User Input: api_questions.md
+  - API Reference:
+    - milc.ansi: api_ansi.md
+    - milc.attrdict: api_attrdict.md
+    - milc.configuration: api_configuration.md
+    - milc.emoji: api_emoji.md
+    - milc.milc: api_milc.md
+    - milc.questions: api_questions.md
+    - milc._sparkline: api__sparkline.md
+    - milc.subcommand.config: api_subcommand_config.md
+plugins:
+  - search:
+      prebuild_index: true
+      separator: '[\s\-\_]+'
+repo_name: clueboard/milc
+repo_url: https://github.com/clueboard/milc
+site_name: MILC — A Python 3 CLI Framework
+site_url: https://milc.clueboard.co/
+theme:
+  features:
+    - navigation.expand
+    - navigation.instant
+    - navigation.sections
+    - search.highlight
+    - search.share
+    - search.suggest
+  font:
+    text: Varela Round
+    code: Source Code Pro
+  icon:
+    repo: fontawesome/brands/github
+  language: en
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: deep purple
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: deep purple
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode

release_docs

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Script to build and release the current documentation
+
+set -e
+set -x
+
+if [ "$1" = "devel" ]; then
+	mike deploy --push devel
+elif [ "$1" = "latest" ]; then
+	RELEASE_VERSION=$(grep 'current_version = ' setup.cfg | grep -o '[0-9].*' | cut -f 1,2 -d .)
+	mike deploy --push --update-aliases $RELEASE_VERSION latest
+else
+	echo "*** You must specify devel or latest!"
+	exit 1
+fi

requirements-dev.txt

@@ -1,5 +1,10 @@
+-r requirements.txt
 flake8
 hjson
+mike
+mkdocs-git-revision-date-plugin
+mkdocs-material
 nose2
+pygments
 semver
 yapf

requirements-release.txt

@@ -1,3 +1,4 @@
+-r requirements-dev.txt
 bumpversion
 flake8
 gitchangelog

setup.cfg

@@ -17,6 +17,8 @@ universal = 1
 [flake8]
 format = pylint
 max_line_length = 200
+exclude =
+	venv
 ignore = 
 	E226
 	E501