docs: Prepare for PyPI publication (#10)

Update installation instructions to reflect ability to use `pip`.
  Add concrete examples of extraction.

  Resolves #9.

Co-authored-by: Glen Whitney <glen@studioinfinity.org>
Reviewed-on: #10
Co-Authored-By: Glen Whitney <glen@nobody@nowhere.net>
Co-Committed-By: Glen Whitney <glen@nobody@nowhere.net>

.drone.yml

@@ -16,17 +16,6 @@ steps:
       - python --version
       - pwd
       - pip install flake8
-### install
-# ## Installation
-#
-# Since there has not yet been a release of mkdocs-semiliterate,
-# you should install it by cloning the repository:
-# ```
-# git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate
-# cd mkdocs-semiliterate
-# pip install .
-# ```
-###
 ### develop
 # You can build the distribution with
 # ```

README.md

@@ -1,6 +1,6 @@
 # MkDocs semiliterate Plugin
 
-This plugin for MkDocs is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://athackst.github.io/mkdocs-simple-plugin). It allows you to include content from one file into another (via `{! ... !}` syntax), using exactly the same extraction specification as the `simple` plugin already uses for identifying documentation in source files.
+This plugin for [MkDocs](http://mkdocs.org) is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://athackst.github.io/mkdocs-simple-plugin). It allows you to include content from one file into another (via `{! ... !}` syntax), using exactly the same extraction specification that the `simple` plugin already uses for identifying documentation in source files.
 <!-- repo: --><!-- site: The current version of mkdocs-semiliterate is {! setup.cfg { extract: {start: name}, terminate: '(\d*\.\d*\.\d*)'} !}. -->
 
 ## Rationale
@@ -13,11 +13,21 @@ Time and trends have not validated Knuth's original vision of "literate programm
 
 *[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information.
 
-The `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.
+The `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 or code that itself serves as documentation to avoid repeating information --- 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 <!-- repo: -->[Usage](http://studioinfinity.org/semiliterate/mkdocs_semiliterate/plugin)<!-- site:[Usage](mkdocs_semiliterate/plugin.md) --> section),
 this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. <!-- repo: -->The [documentation site](http://studioinfinity.org/semiliterate)<!-- site:This documentation site --> is, of course, produced by MkDocs using the semiliterate plugin.
 
+## Installation
+
+The mkdocs-semiliterate package which provides the `semiliterate` plugin for MkDocs is available via PyPI:
+
+`python3 -m pip install mkdocs-semiliterate`
+
+or of course if your `pip` is already set up to use a Python 3.5 (or later) installation, just
+
+`pip install mkdocs-semiliterate`
+
 ## License
 
 This software is licensed under [Apache 2.0](LICENSE).

mkdocs.yml

@@ -1,7 +1,6 @@
 site_name: MkDocs semiliterate plugin
 nav:
 - Overview: README.md
-- Installation: drone_install.md
 - Usage: mkdocs_semiliterate/plugin.md
 - Developing: drone_develop.md
 plugins:
@@ -22,15 +21,10 @@ plugins:
           start: '### develop'
           stop: '^\s*###'
           replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
-      - pattern: '.drone.yml'
-        destination: 'drone_install.md'
-        extract:
-          start: '### install'
-          stop: '^\s*###'
-          replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
 markdown_extensions:
 - abbr
 - def_list
+- smarty
 theme:
   name: readthedocs
 docs_dir: mkdocs_semiliterate # dummy

mkdocs_semiliterate/plugin.py

@@ -1,11 +1,11 @@
 """ md
 ## Usage
 
-Once this plugin is [installed](../drone_install.md), in your `mkdocs.yml`
-file just replace the plugin name `simple` with `semiliterate`. It accepts all
-of the same parameters, so `mkdocs` will still work as before, and
-you will have immediate access to all of the following extensions. (Note that
-this documentation assumes a familiarity with the
+Once this plugin is [installed](../README.md#installation), just replace
+the plugin name `simple` with `semiliterate` in your `mkdocs.yml` file.
+It accepts all of the same parameters, so `mkdocs` will still work as before,
+and you will have immediate access to all of the following extensions.
+(Note that this documentation assumes a familiarity with the
 [usage](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/)
 of the `simple` plugin.)
 """
@@ -20,7 +20,7 @@ import yaml
 
 
 class StreamInclusion(StreamExtract):
-    """ md  An extension of the StreamExtract class which adds
+    r""" md  An extension of the StreamExtract class which adds
 
 ### Inclusion syntax
 
@@ -36,19 +36,43 @@ enclosed in single or double quotes. Note that FILENAME is interpreted relative
 to the directory in which the file containing the `{! .. !}` expression
 resides. The YAML is interpreted exactly as the extraction options to a
 `semiliterate` item as
-[documented](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/index.html#plugin_usage)
+[documented](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/index.html#semiliterate)
 for the `simple` extension. The text extracted from FILENAME
 is interpolated at the current location in the file currently being written.
 Recursive inclusion is supported.
 
-Note that the `{! ... !}` directive must be in lines that semiliterate would
-normally copy. That is, it does not examine lines after the `terminate` regexp,
-or when no mode of extraction is active. It also doesn't check any text written
-from lines that match these special expressions like `start` and `stop`.
+The simplest example of such an inclusion directive is just
+`{! boilerplate.md !}`, which (because of the conventions for extraction
+parameters) simply interpolates the entire contents of `boilerplate.md`
+at the current location.
+
+For an example that uses more of the extraction parameters, the current
+version number of mkdocs-semiliterate is extracted into the
+[Overview](../README.md) of this documentation via
+
+` {! ../README.md extract: { start: 'repo:.*(\{!.*!\})' }
+terminate: Rationale
+!}`
+
+to take advantage of the beginning of the `setup.cfg` file:
+```
+{! ../setup.cfg terminate: long !}...
+```
+
+(and of course both of the code snippets just above are extracted into this
+page with `{! ... !}`, as you can see in the
+[source code](https://code.studioinfinity.org/glen/mkdocs-semiliterate/src/branch/main/mkdocs_semiliterate/plugin.py)
+for the plugin.)
+
+Note that a `{! ... !}` directive must be in a line that semiliterate would
+normally copy. That is, semiliterate does not examine lines after
+the `terminate` regexp, or when no mode of extraction is active.
+It also doesn't check any text written from lines that match these
+special expressions, including `start` and `stop`.
 Moreover, on such normally-transcribed lines,
 it's the text **after** the application of any semiliterate `replace`ments that
 is checked for `{! ... !}`.
-     """
+     """  # noqa: E501
 
     include_open = re.compile(r'''(?<![`\\])(\{\!\s*)([\s'"])''')
     include_quoted_file = re.compile(
@@ -108,7 +132,7 @@ class SemiliteratePlugin(SimplePlugin):
     r""" md   An extension of the mkdocs-simple-plugin
 
 In addition, block-comment markdown `/** md` ... `**/` is by
-default scanned for in all files with an extension, as it's valid in so many
+default scanned for in all files with _any_ extension, as it's valid in so many
 disparate languages.
 
 ### Additional plugin parameters
@@ -163,7 +187,8 @@ terminate: '^\s*\)'
         #    copied "as-is", except possibly for embedded inclusions.
         #    On the other hand, setting this parameter to `{enable: false}`
         #    (which is also the default when `copy_standard_markdown` is true)
-        #    will prevent automatic extraction from standard Markdown files.
+        #    will prevent automatic extraction (and hence disable
+        #    inclusion-directive processing) from standard Markdown files.
     )
 
     def build_docs(self):

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-semiliterate
-version = 0.1.0
+version = 0.1.1
 description = Extension of mkdocs-simple-plugin adding easy content inclusion
 long_description = file: README.md
 long_description_content_type = text/markdown

tests/bootstrap.manifest

@@ -5,8 +5,6 @@ site/css/theme.css
 site/css/theme_extra.css
 site/drone_develop
 site/drone_develop/index.html
-site/drone_install
-site/drone_install/index.html
 site/index.html
 site/LICENSE
 site/mkdocs_semiliterate