reorganized docs (#59)

.github/workflows/release.yml

@@ -60,7 +60,6 @@ jobs:
           push: true
       - name: Merge release
         uses: everlytic/branch-merge@1.1.0
-        if: steps.waitforstatuschecks.outputs.status == 'success'
         with:
           github_token: ${{ secrets.RELEASEBOT_TOKEN }}
           source_ref: release/v${{ env.VERSION }}

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing
+# Contributing Guide
 
 First off, thanks for taking the time to contribute! :rocket:
 

mkdocs.yml

@@ -1,16 +1,15 @@
-theme:
-  name: "material"
-  palette:
-    primary: green
-    accent: green
-
+site_name: athackst/mkdocs-simple-plugin
+docs_dir: docs
 plugins:
   - search
   - simple:
       ignore_folders:
         - tests
-        - mkdocs_simple_plugin
-
+theme:
+  name: material
+  palette:
+    primary: green
+    accent: green
 markdown_extensions:
   - admonition
   - pymdownx.superfences
@@ -19,7 +18,6 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
-
 extra:
   social:
     - icon: fontawesome/brands/twitter
@@ -28,5 +26,13 @@ extra:
       link: https://hub.docker.com/u/athackst
     - icon: fontawesome/regular/laugh
       link: https://allisonthackston.com
-
 edit_uri: ""
+nav:
+  - About: README.md
+  - Mkdocs Simple Generator: mkdocs_simple_plugin/generator.md
+  - Mkdocs Simple Plugin: mkdocs_simple_plugin/plugin.md
+  - Github Action: action.md
+  - Docker: docker.md
+  - Developers:
+      - Developing: mkdocs_simple_plugin/README.md
+      - Contributing Guide: CONTRIBUTING.md

mkdocs_simple_plugin/README.md

@@ -1,29 +1,49 @@
-# mkdocs-simple-plugin
+# Developing
 
-| [Docs](http://athackst.github.io/mkdocs-simple-plugin) | [Code](http://github.com/athackst/mkdocs-simple-plugin)  | [PyPi](https://pypi.org/project/mkdocs-simple-plugin/) | [Docker](https://hub.docker.com/r/athackst/mkdocs-simple-plugin) |
+## Prerequisites
 
-![Test](https://github.com/athackst/mkdocs-simple-plugin/workflows/Test/badge.svg) ![Docs](https://github.com/athackst/mkdocs-simple-plugin/workflows/Docs/badge.svg) ![Docker](https://img.shields.io/docker/pulls/athackst/mkdocs-simple-plugin?color=blue) ![pypi](https://img.shields.io/pypi/dm/mkdocs-simple-plugin?color=blue)
+You will need to have [mkdocs](https://www.mkdocs.org/) installed on your system.  I recommend installing it via pip to get the latest version.
 
-This plugin enables you to build documentation from markdown files interspersed within your code using [mkdocs](https://www.mkdocs.org/).  It is designed for the way developers commonly write documentation in their own code -- with simple markdown files.
+```bash
+sudo apt-get install python-pip
+pip install --upgrade pip --user
+pip install mkdocs --user
+```
 
-## About
+If you want to run the test suite, you'll also need 'bats'
 
-You may be wondering why you would want to generate a static site for your project, without doing the typical "wiki" thing of consolidating all documentation within a single `docs` folder or using a single `README` file.
+```bash
+sudo apt-get install bats
+```
 
-* **My repository is too big for a single documentation source.**
+## Local install
 
-    Sometimes it isn't really feasible to consolidate all documentation within an upper level `docs` directory.  This is often the case with medium/large repositories.  In general, if your code base is too large to fit well within a single `include` directory, your code base is probably also too large for documentation to fit within a single `docs` directory.  
+Install the package locally with
 
-    Since it's typically easier to keep documentation up to date when it lives as close to the code as possible, it is better to create multiple sources for documentation.
+```bash
+pip install -e .
+```
 
-* **My repository is too simple for advanced documentation.**
+## Testing
 
-    If your code base is _very very_ large, something like the [monorepo plugin](https://github.com/spotify/mkdocs-monorepo-plugin) might better fit your needs.
+Testing involves both linting with flake8
 
-    For most other medium+ repositories that have grown over time, you probably have scattered documentation throughout your code.  By combining all of that documentation while keeping folder structure, you can better surface and collaborate with others. And, let's face it.  That documentation is probably all in markdown, since github renders it nicely.
+```bash
+./tests/test_flake8.sh
+```
 
-* **I want a pretty documentation site without the hassle.**
+and testing with `bats`
 
-    Finally, you may be interested in this plugin if you have a desire for stylized documentation, but don't want to invest the time/energy in replicating information you already have in your README.md files, and you want to keep them where they are (thank you very much).
+```bash
+./tests/integration/test.bats
+```
 
-See [mkdocs-simple-plugin](http://athackst.github.io/mkdocs-simple-plugin) for usage.
+If you want to test against all the different versions of python, run the local test script.
+
+```bash
+./tests/test_local.sh
+```
+
+## VSCode
+
+Included in this package is a VSCode workspace and development container.  See [how I develop with vscode and docker](https://www.allisonthackston.com/articles/docker_development.html) and [how I use vscode tasks](https://www.allisonthackston.com/articles/vscode_tasks.html).

mkdocs_simple_plugin/gen.py

@@ -70,16 +70,17 @@ def setup_config():
 
 @click.command()
 @click.option('--build/--no-build', default=True, help="build the site using mkdocs build")
-@click.argument('build-args', nargs=-1)
-def main(build, build_args):
+@click.option('--serve/--no-serve', default=False, help="serve the site using mkdocs serve")
+@click.argument('mkdocs-args', nargs=-1)
+def main(build, serve, mkdocs_args):
     """
     Generate and build a mkdocs site.
-
-    See mkdocs build -h for additional build args.
     """
     setup_config()
     if build:
-        os.system("mkdocs build " + " ".join(build_args))
+        os.system("mkdocs build " + " ".join(mkdocs_args))
+    if serve:
+        os.system("mkdocs serve " + " ".join(mkdocs_args))
 
 
 if __name__ == "__main__":

docs/mkdocs-simple-gen.md → mkdocs_simple_plugin/generator.md

@@ -1,6 +1,6 @@
-# MkDocs Simple Gen
+# Mkdocs Simple Generator
 
-A program that will automatically create a `mkdocs.yml` configuration file (only if needed) and optionally install dependencies, build, and serve the site.
+`mkdocs_simple_gen` is a program that will automatically create a `mkdocs.yml` configuration file (only if needed) and optionally install dependencies, build, and serve the site.
 
 ## Installation
 
@@ -12,7 +12,6 @@ pip install mkdocs-simple-plugin
 
 _Python 3.x, 3.5, 3.6, 3.7, 3.8, 3.9 supported._
 
-
 ### Command line options
 
 See `--help`