refactor: Build on top of released mkdocs-simple-plugin v0.4.0 #8

Merged
glen merged 3 commits from release_prep into main 2021-02-09 06:26:40 +00:00
6 changed files with 31 additions and 27 deletions

View File

@ -16,27 +16,17 @@ steps:
- python --version - python --version
- pwd - pwd
- pip install flake8 - pip install flake8
- cd ..
### install ### install
# ## Installation # ## Installation
# #
# At the moment, `semiliterate` relies on the latest pre-release version of # Since there has not yet been a release of mkdocs-semiliterate,
# `mkdocs-simple-plugin`. Therefore, you must clone and install that repository # you should install it by cloning the repository:
# before installing `semiliterate`.
# ```
- git clone https://github.com/athackst/mkdocs-simple-plugin.git
- cd mkdocs-simple-plugin
- pip install .
# ```
# Once that's in place, you can install semiliterate; right now as there has
# not yet been a release, you should do that by cloning and installing as well:
# ``` # ```
# git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate # git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate
# cd mkdocs-semiliterate # cd mkdocs-semiliterate
# pip install . # pip install .
# ``` # ```
### ###
- cd ../src
### develop ### develop
# You can build the distribution with # You can build the distribution with
# ``` # ```

View File

@ -1,15 +1,19 @@
# 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 adds `{! ... !}` syntax for including content from one file into another (and a couple of other small ease-of-use tweaks). 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.
<!-- 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
Time and trends have not validated Knuth's original vision of "literate programming" as a mainstream practice. Nevertheless, there remain significant advantages to incorporating all documentation, including user-guide-style narrative, into the source code for a project. These advantages include ease of maintenance and synchronization of code and documentation, and opportunities to make the ensemble of your code and documentation more DRY. Thus, it's worth using a "semiliterate" programming style, in which: code is arranged as dictated by best software engineering practices; documentation is co-located in the same files next to the implementing code; and tools are provided for extracting and assembling that documentation into readable form. Time and trends have not validated Knuth's original vision of "literate programming" as a mainstream practice. Nevertheless, there remain significant advantages to incorporating all documentation, including user-guide-style narrative, into the source code for a project. These advantages include ease of maintenance and synchronization of code and documentation, and opportunities to make the ensemble of your code and documentation more DRY. Thus, it's worth using a "semiliterate" programming style, in which
* code is arranged as dictated by best software engineering practices
* documentation is co-located in the same files next to the implementing code
* and tools are provided for extracting and assembling that documentation into readable form.
*[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 mkdocs-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 -- 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.

View File

@ -10,7 +10,6 @@ plugins:
merge_docs_dir: false merge_docs_dir: false
ignore_folders: [build, dist, tests, semiliterate] ignore_folders: [build, dist, tests, semiliterate]
include_extensions: [LICENSE] include_extensions: [LICENSE]
report_docs_build: true
extract_standard_markdown: extract_standard_markdown:
extract: extract:
replace: [['^(.*)<!-- repo: -->.*<!-- site:(.*?) -->(.*\s*)$', '\1\2\3']] replace: [['^(.*)<!-- repo: -->.*<!-- site:(.*?) -->(.*\s*)$', '\1\2\3']]

View File

@ -0,0 +1 @@
"""mkdocs_semiliterate package."""

View File

@ -152,7 +152,7 @@ terminate: '^\s*\)'
# `semiliterate` still incorporates all standard Markdown files # `semiliterate` still incorporates all standard Markdown files
# because of the following `extract_standard_markdown` parameter. # because of the following `extract_standard_markdown` parameter.
('extract_standard_markdown', ('extract_standard_markdown',
config_options.Type(dict, default={})), config_options.Type(dict, default={}))
# If the `enable` key of this dict parameter is true # If the `enable` key of this dict parameter is true
# (it defaults to the opposite of `copy_standard_markdown`), # (it defaults to the opposite of `copy_standard_markdown`),
# it adds a semiliterate block causing extraction (and hence # it adds a semiliterate block causing extraction (and hence
@ -164,17 +164,9 @@ terminate: '^\s*\)'
# 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 from standard Markdown files.
('report_docs_build',
config_options.Type(bool, default=False))
# If true, the name of the temporary directory to which generated docs
# files are copied/extracted will be written to standard output
# (even if the `-v` verbose option to mkdocs is not specified).
) )
def build_docs(self): def build_docs(self):
if self.config['report_docs_build']:
utils.log.info(
f"semiliterate: generating docs in {self.build_docs_dir}")
self.exclude_extensions = self.config['exclude_extensions'] self.exclude_extensions = self.config['exclude_extensions']
dflt_enable = False dflt_enable = False
if not self.config['copy_standard_markdown']: if not self.config['copy_standard_markdown']:

View File

@ -1,12 +1,30 @@
[metadata] [metadata]
name = mkdocs-semiliterate name = mkdocs-semiliterate
version = 0.0.12 version = 0.1.0
description = Extension of mkdocs-simple-plugin adding easy content inclusion
long_description = file: README.md
long_description_content_type = text/markdown
keywords = mkdocs literate
url = http://studioinfinity.org/semiliterate
project_urls =
Issues = https://code.studioinfinity.org/glen/mkdocs-semiliterate/issues,
Documentation = http://studioinfinity.org/semiliterate,
Source Code = http://code.studioinfinity.org/glen/mkdocs-semiliterate
author = Glen Whitney
author_email = glen@studioinfinity.org
classifiers =
Development Status :: 4 - Beta
Intended Audience :: Developers
Intended Audience :: Information Technology
Programming Language :: Python
Programming Language :: Python :: 3 :: Only
license = Apache-2.0
[options] [options]
packages = mkdocs_semiliterate packages = mkdocs_semiliterate
install_requires = install_requires =
mkdocs mkdocs
mkdocs-simple-plugin mkdocs-simple-plugin>=0.4.0
[options.entry_points] [options.entry_points]
mkdocs.plugins = mkdocs.plugins =