docs: Prepare for PyPI publication #10
11
.drone.yml
11
.drone.yml
@ -16,17 +16,6 @@ steps:
|
|||||||
- python --version
|
- python --version
|
||||||
- pwd
|
- pwd
|
||||||
- pip install flake8
|
- 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
|
### develop
|
||||||
# You can build the distribution with
|
# You can build the distribution with
|
||||||
# ```
|
# ```
|
||||||
|
14
README.md
14
README.md
@ -1,6 +1,6 @@
|
|||||||
# MkDocs semiliterate Plugin
|
# 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*)'} !}. -->
|
<!-- repo: --><!-- site: The current version of mkdocs-semiliterate is {! setup.cfg { extract: {start: name}, terminate: '(\d*\.\d*\.\d*)'} !}. -->
|
||||||
|
|
||||||
## Rationale
|
## 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.
|
*[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),
|
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.
|
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
|
## License
|
||||||
|
|
||||||
This software is licensed under [Apache 2.0](LICENSE).
|
This software is licensed under [Apache 2.0](LICENSE).
|
||||||
|
@ -1,7 +1,6 @@
|
|||||||
site_name: MkDocs semiliterate plugin
|
site_name: MkDocs semiliterate plugin
|
||||||
nav:
|
nav:
|
||||||
- Overview: README.md
|
- Overview: README.md
|
||||||
- Installation: drone_install.md
|
|
||||||
- Usage: mkdocs_semiliterate/plugin.md
|
- Usage: mkdocs_semiliterate/plugin.md
|
||||||
- Developing: drone_develop.md
|
- Developing: drone_develop.md
|
||||||
plugins:
|
plugins:
|
||||||
@ -22,15 +21,10 @@ plugins:
|
|||||||
start: '### develop'
|
start: '### develop'
|
||||||
stop: '^\s*###'
|
stop: '^\s*###'
|
||||||
replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
|
replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
|
||||||
- pattern: '.drone.yml'
|
|
||||||
destination: 'drone_install.md'
|
|
||||||
extract:
|
|
||||||
start: '### install'
|
|
||||||
stop: '^\s*###'
|
|
||||||
replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
|
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
- abbr
|
- abbr
|
||||||
- def_list
|
- def_list
|
||||||
|
- smarty
|
||||||
theme:
|
theme:
|
||||||
name: readthedocs
|
name: readthedocs
|
||||||
docs_dir: mkdocs_semiliterate # dummy
|
docs_dir: mkdocs_semiliterate # dummy
|
||||||
|
@ -1,11 +1,11 @@
|
|||||||
""" md
|
""" md
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Once this plugin is [installed](../drone_install.md), in your `mkdocs.yml`
|
Once this plugin is [installed](../README.md#installation), just replace
|
||||||
file just replace the plugin name `simple` with `semiliterate`. It accepts all
|
the plugin name `simple` with `semiliterate` in your `mkdocs.yml` file.
|
||||||
of the same parameters, so `mkdocs` will still work as before, and
|
It accepts all of the same parameters, so `mkdocs` will still work as before,
|
||||||
you will have immediate access to all of the following extensions. (Note that
|
and you will have immediate access to all of the following extensions.
|
||||||
this documentation assumes a familiarity with the
|
(Note that this documentation assumes a familiarity with the
|
||||||
[usage](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/)
|
[usage](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/)
|
||||||
of the `simple` 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
|
to the directory in which the file containing the `{! .. !}` expression
|
||||||
resides. The YAML is interpreted exactly as the extraction options to a
|
resides. The YAML is interpreted exactly as the extraction options to a
|
||||||
`semiliterate` item as
|
`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
|
for the `simple` extension. The text extracted from FILENAME
|
||||||
is interpolated at the current location in the file currently being written.
|
is interpolated at the current location in the file currently being written.
|
||||||
Recursive inclusion is supported.
|
Recursive inclusion is supported.
|
||||||
|
|
||||||
Note that the `{! ... !}` directive must be in lines that semiliterate would
|
The simplest example of such an inclusion directive is just
|
||||||
normally copy. That is, it does not examine lines after the `terminate` regexp,
|
`{! boilerplate.md !}`, which (because of the conventions for extraction
|
||||||
or when no mode of extraction is active. It also doesn't check any text written
|
parameters) simply interpolates the entire contents of `boilerplate.md`
|
||||||
from lines that match these special expressions like `start` and `stop`.
|
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,
|
Moreover, on such normally-transcribed lines,
|
||||||
it's the text **after** the application of any semiliterate `replace`ments that
|
it's the text **after** the application of any semiliterate `replace`ments that
|
||||||
is checked for `{! ... !}`.
|
is checked for `{! ... !}`.
|
||||||
@ -108,7 +132,7 @@ class SemiliteratePlugin(SimplePlugin):
|
|||||||
r""" md An extension of the mkdocs-simple-plugin
|
r""" md An extension of the mkdocs-simple-plugin
|
||||||
|
|
||||||
In addition, block-comment markdown `/** md` ... `**/` is by
|
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.
|
disparate languages.
|
||||||
|
|
||||||
### Additional plugin parameters
|
### Additional plugin parameters
|
||||||
@ -163,7 +187,8 @@ terminate: '^\s*\)'
|
|||||||
# copied "as-is", except possibly for embedded inclusions.
|
# copied "as-is", except possibly for embedded inclusions.
|
||||||
# On the other hand, setting this parameter to `{enable: false}`
|
# On the other hand, setting this parameter to `{enable: false}`
|
||||||
# (which is also the default when `copy_standard_markdown` is true)
|
# (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):
|
def build_docs(self):
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
[metadata]
|
[metadata]
|
||||||
name = mkdocs-semiliterate
|
name = mkdocs-semiliterate
|
||||||
version = 0.1.0
|
version = 0.1.1
|
||||||
description = Extension of mkdocs-simple-plugin adding easy content inclusion
|
description = Extension of mkdocs-simple-plugin adding easy content inclusion
|
||||||
long_description = file: README.md
|
long_description = file: README.md
|
||||||
long_description_content_type = text/markdown
|
long_description_content_type = text/markdown
|
||||||
|
Loading…
Reference in New Issue
Block a user