From 92bf9be90b8c04c8fc5ca491a2f35a97c7e6c6a0 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 9 Feb 2021 09:13:51 -0800 Subject: [PATCH 1/4] docs: Prepare for PyPI publication Update installation instructions to reflect ability to use `pip`. Add concrete examples of extraction. Resolves #9. --- .drone.yml | 11 -------- README.md | 14 ++++++++-- mkdocs.yml | 8 +----- mkdocs_semiliterate/plugin.py | 49 ++++++++++++++++++++++++++--------- setup.cfg | 2 +- 5 files changed, 51 insertions(+), 33 deletions(-) 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..ccaab3b 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](https://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..b42a4a0 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.) """ @@ -36,15 +36,39 @@ 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 `{! ... !}`. @@ -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): diff --git a/setup.cfg b/setup.cfg index 6c93959..f5f3d19 100644 --- a/setup.cfg +++ b/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 -- 2.34.1 From 216a2bdeb5814264d1617f6095e6039d4cff4d31 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 9 Feb 2021 09:21:15 -0800 Subject: [PATCH 2/4] chore: Satisfy flake8 --- mkdocs_semiliterate/plugin.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py index b42a4a0..1d58982 100644 --- a/mkdocs_semiliterate/plugin.py +++ b/mkdocs_semiliterate/plugin.py @@ -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,7 +36,8 @@ 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#semiliterate) +[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. @@ -61,7 +62,8 @@ to take advantage of the beginning of the `setup.cfg` file: (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) +[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 -- 2.34.1 From 1b621ea13f40994c55b5315ac0a3574595607956 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 9 Feb 2021 09:27:20 -0800 Subject: [PATCH 3/4] chore: Update bootstrap.manifest --- tests/bootstrap.manifest | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/bootstrap.manifest b/tests/bootstrap.manifest index 77da37a..02e9a20 100644 --- a/tests/bootstrap.manifest +++ b/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 -- 2.34.1 From 072a57503b3ec8b0d96a65560655ddc3bea957f6 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 9 Feb 2021 09:40:31 -0800 Subject: [PATCH 4/4] chore: Make HtmlProofer happy by shutting up flake8 with # noqa --- README.md | 2 +- mkdocs_semiliterate/plugin.py | 8 +++----- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ccaab3b..ff88169 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MkDocs semiliterate Plugin -This plugin for [MkDocs](https://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. +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 diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py index 1d58982..e366576 100644 --- a/mkdocs_semiliterate/plugin.py +++ b/mkdocs_semiliterate/plugin.py @@ -36,8 +36,7 @@ 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#semiliterate) +[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. @@ -62,8 +61,7 @@ to take advantage of the beginning of the `setup.cfg` file: (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) +[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 @@ -74,7 +72,7 @@ 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'''(?