docs: Prepare for PyPI publication #10

Merged
glen merged 4 commits from pip_install into main 2021-02-09 17:47:03 +00:00
5 changed files with 51 additions and 33 deletions
Showing only changes of commit 92bf9be90b - Show all commits

View File

@ -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
# ```

View File

@ -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.
<!-- 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).

View File

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

View File

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

View File

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