Metadata-Version: 2.1
Name: mkdocs-semiliterate
Version: 0.2.0
Summary: Extension of mkdocs-simple-plugin adding easy content inclusion
Home-page: http://studioinfinity.org/semiliterate
Author: Glen Whitney
Author-email: glen@studioinfinity.org
License: Apache-2.0
Project-URL: Issues, https://code.studioinfinity.org/glen/mkdocs-semiliterate/issues
Project-URL: Documentation, http://studioinfinity.org/semiliterate
Project-URL: Source Code, http://code.studioinfinity.org/glen/mkdocs-semiliterate
Description: # MkDocs semiliterate Plugin
        
        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
        
        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 `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).
        
Keywords: mkdocs literate
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Description-Content-Type: text/markdown
