From be97842c90da43d84b0359a39013feb69f8f158f Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Mon, 8 Feb 2021 21:41:24 -0800 Subject: [PATCH] refactor: Remove report_docs_build parameter The underlying mkdocs_simple_plugin now itself reports the doc build directory. This commit also updates the documentation slightly. --- README.md | 10 +++++++--- mkdocs.yml | 1 - mkdocs_semiliterate/plugin.py | 10 +--------- setup.cfg | 2 +- 4 files changed, 9 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a1ff052..8fabe19 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ # 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. ## 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. -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 [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. diff --git a/mkdocs.yml b/mkdocs.yml index b79e254..dd9eb1b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,6 @@ plugins: merge_docs_dir: false ignore_folders: [build, dist, tests, semiliterate] include_extensions: [LICENSE] - report_docs_build: true extract_standard_markdown: extract: replace: [['^(.*).*(.*\s*)$', '\1\2\3']] diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py index 806d269..ccd0b83 100644 --- a/mkdocs_semiliterate/plugin.py +++ b/mkdocs_semiliterate/plugin.py @@ -152,7 +152,7 @@ terminate: '^\s*\)' # `semiliterate` still incorporates all standard Markdown files # because of the following `extract_standard_markdown` parameter. ('extract_standard_markdown', - config_options.Type(dict, default={})), + config_options.Type(dict, default={})) # If the `enable` key of this dict parameter is true # (it defaults to the opposite of `copy_standard_markdown`), # 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}` # (which is also the default when `copy_standard_markdown` is true) # 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): - 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'] dflt_enable = False if not self.config['copy_standard_markdown']: diff --git a/setup.cfg b/setup.cfg index 2964cbb..2e30f2d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = mkdocs-semiliterate -version = 0.0.12 +version = 0.0.13 [options] packages = mkdocs_semiliterate