From ec9c7e57cecf656fd284185106ab482cd4da1dad Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Thu, 7 Jan 2021 22:39:40 -0800 Subject: [PATCH] chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site. --- .gitignore | 3 +++ README.md | 22 ++++++++++++++++++++-- mkdocs.yml | 18 ++++++++++++++++++ mkdocs_semiliterate/plugin.py | 19 +++++++++++++++++++ pyproject.toml | 3 +++ setup.cfg | 13 +++++++++++++ 6 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 mkdocs.yml create mode 100644 mkdocs_semiliterate/plugin.py create mode 100644 pyproject.toml create mode 100644 setup.cfg diff --git a/.gitignore b/.gitignore index f8b73e7..e82ff19 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# Backups +*~ + # ---> Python # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/README.md b/README.md index 5fb6643..c9d968b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,21 @@ -# mkdocs-semiliterate +# MkDocs semiliterate Plugin -An extension of the mkdocs-simple-plugin that adds syntax for including content from other files \ No newline at end of file +This plugin for MkDocs is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://athackst.github.io/mkdocs-simple-plugin). It adds `{! ... !}` syntax for including content from one file into another (and a couple of other small usability tweaks). + +## Rationale + +Time and trends have not validated Knuth's original vision of "literate programming" as a mainstream practice. Nevertheless, there remain significant advantages to incorporating all documentation, including user-guide-style narrative, into the source code for a project. These advantages include ease of maintenance and synchronization of code and documentation, and opportunities to make the ensemble of your code and documentation more DRY. Thus, it's worth using a "semiliterate" programming style, in which: code is arranged as dictated by best software engineering practices; documentation is co-located in the same files next to the implementing code; and tools are provided for extracting and assembling that documentation into readable form. + +*[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information. + +The mkdocs-simple-plugin goes a long way toward creating a semiliterate programming environment. However, in creating narrative documentation, it's very useful to be able to quote or incorporate content -- whether that be documentation blocks or code examples -- from one file into another. To satisfy that need, this `semiliterate` plugin extends (i.e, literally inherits from) the `simple` plugin and adds a syntax for such inclusion. + +With a few other small ease-of-use tweaks (documented in the Usage section), this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. The documentation site is, of course, produced by MkDocs using the semiliterate plugin. + +## Installation + +To be written. + +## License + +This software is licensed under [Apache 2.0](LICENSE). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f322ab0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,18 @@ +site_name: MkDocs semiliterate plugin +nav: +- Overview: README.md +- Usage: mkdocs_semiliterate/plugin.md +plugins: +- search +- semiliterate: + merge_docs_dir: false + ignore_folders: [dist] + include_extensions: [LICENSE] +# semiliterate: +# - pattern: '(\.md)$' +# replace: [['^(.*).*(.*\s*)$', '\1\2\3']] +markdown_extensions: +- abbr +theme: + name: readthedocs +docs_dir: mkdocs_semiliterate # dummy diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py new file mode 100644 index 0000000..cce1b36 --- /dev/null +++ b/mkdocs_semiliterate/plugin.py @@ -0,0 +1,19 @@ +""" md +## Usage + +Once this plugin is [installed](../README.md#installation), in your `mkdocs.yml` +file just replace the plugin name `simple` with `semiliterate`. It accepts all +of the same parameters as `simple`, so `mkdocs` will still work as before, and +you will have immediate access to all of the following extensions: + +### Inclusion syntax + +To be documented when implemented. +""" + +import mkdocs +from mkdocs.config import config_options +from mkdocs_simple_plugin.plugin import SimplePlugin + +class SemiliteratePlugin(SimplePlugin): + """ So far, just an alias for simple """ diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..9787c3b --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,3 @@ +[build-system] +requires = ["setuptools", "wheel"] +build-backend = "setuptools.build_meta" diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..4f88e92 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,13 @@ +[metadata] +name = mkdocs-semiliterate +version = 0.0.1 + +[options] +packages = mkdocs_semiliterate +install_requires = + mkdocs + mkdocs-simple-plugin + +[options.entry_points] +mkdocs.plugins = + semiliterate = mkdocs_semiliterate.plugin:SemiliteratePlugin