diff --git a/.drone.yml b/.drone.yml index 450b451..3ce60f1 100644 --- a/.drone.yml +++ b/.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 # ``` diff --git a/README.md b/README.md index 8fabe19..ff88169 100644 --- a/README.md +++ b/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. ## 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 [Usage](http://studioinfinity.org/semiliterate/mkdocs_semiliterate/plugin) section), this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. The [documentation site](http://studioinfinity.org/semiliterate) 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). diff --git a/mkdocs.yml b/mkdocs.yml index dd9eb1b..99bac9b 100644 --- a/mkdocs.yml +++ b/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 diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py index ccd0b83..e366576 100644 --- a/mkdocs_semiliterate/plugin.py +++ b/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'''(?