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>

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):