Browse Source

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: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/10
Co-Authored-By: Glen Whitney <glen@nobody@nowhere.net>
Co-Committed-By: Glen Whitney <glen@nobody@nowhere.net>
simple1_0 0.1.1
Glen Whitney 10 months ago
parent
commit
b9d9b7ac0d
  1. 11
      .drone.yml
  2. 14
      README.md
  3. 8
      mkdocs.yml
  4. 53
      mkdocs_semiliterate/plugin.py
  5. 2
      setup.cfg
  6. 2
      tests/bootstrap.manifest

11
.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
# ```

14
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).

8
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

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

2
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
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

Loading…
Cancel
Save