#  MkDocs semiliterate Plugin
This plugin for [MkDocs](http://mkdocs.org) is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://www.althack.dev/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*)', ensurelines: false} !}. -->
<!-- repo: --><!-- site: It is built on mkdocs-simple-plugin v{! setup.cfg { extract: {start: 'mkdocs~=', stop: '(\d*\.\d*\.?\d*)'}, ensurelines: false} !}. -->
## 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 and Acknowledgments
This software is licensed under [Apache 2.0](LICENSE). [Icons8](https://icons8.com/icon/115368/ask-question) provided the icon.
Raw data
{
"_id": null,
"home_page": "http://studioinfinity.org/semiliterate",
"name": "mkdocs-semiliterate",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "mkdocs literate",
"author": "Glen Whitney",
"author_email": "glen@studioinfinity.org",
"download_url": "https://files.pythonhosted.org/packages/08/00/0cf88132042d7dedcab1ef138ce57ea79323d6a28c469d2db592edc7c912/mkdocs_semiliterate-0.8.2.tar.gz",
"platform": null,
"description": "#  MkDocs semiliterate Plugin\n\nThis plugin for [MkDocs](http://mkdocs.org) is an extension of Allison Thackston's excellent [mkdocs-simple-plugin](https://www.althack.dev/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.\n<!-- repo: --><!-- site: The current version of mkdocs-semiliterate is {! setup.cfg { extract: {start: name}, terminate: '(\\d*\\.\\d*\\.\\d*)', ensurelines: false} !}. -->\n<!-- repo: --><!-- site: It is built on mkdocs-simple-plugin v{! setup.cfg { extract: {start: 'mkdocs~=', stop: '(\\d*\\.\\d*\\.?\\d*)'}, ensurelines: false} !}. -->\n\n## Rationale\n\nTime 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\n\n* code is arranged as dictated by best software engineering practices\n* documentation is co-located in the same files next to the implementing code\n* and tools are provided for extracting and assembling that documentation into readable form.\n\n*[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information.\n\nThe `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.\n\nWith 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),\nthis 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.\n\n## Installation\n\nThe mkdocs-semiliterate package which provides the `semiliterate` plugin for MkDocs is available via PyPI:\n\n`python3 -m pip install mkdocs-semiliterate`\n\nor of course if your `pip` is already set up to use a Python 3.5 (or later) installation, just\n\n`pip install mkdocs-semiliterate`\n\n## License and Acknowledgments\n\nThis software is licensed under [Apache 2.0](LICENSE). [Icons8](https://icons8.com/icon/115368/ask-question) provided the icon.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Extension of mkdocs-simple-plugin adding easy content inclusion",
"version": "0.8.2",
"project_urls": {
"Documentation": "http://studioinfinity.org/semiliterate",
"Homepage": "http://studioinfinity.org/semiliterate",
"Issues": "https://code.studioinfinity.org/glen/mkdocs-semiliterate/issues",
"Source": "http://code.studioinfinity.org/glen/mkdocs-semiliterate",
"Source Code": "http://code.studioinfinity.org/glen/mkdocs-semiliterate"
},
"split_keywords": [
"mkdocs",
"literate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "930a09b0a9879cb26c2adc863bf9af5cc346834b7c697dbcb9737e3eb0fdddd0",
"md5": "621c81b985b2800276806c683129478d",
"sha256": "1838bbdc93f8fe29b9e54709ac455d0d7d7e4eed3ee9f52747fbdb251b7138af"
},
"downloads": -1,
"filename": "mkdocs_semiliterate-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "621c81b985b2800276806c683129478d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15242,
"upload_time": "2024-11-02T19:32:24",
"upload_time_iso_8601": "2024-11-02T19:32:24.355684Z",
"url": "https://files.pythonhosted.org/packages/93/0a/09b0a9879cb26c2adc863bf9af5cc346834b7c697dbcb9737e3eb0fdddd0/mkdocs_semiliterate-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "08000cf88132042d7dedcab1ef138ce57ea79323d6a28c469d2db592edc7c912",
"md5": "76fbca8c15b33bb30e683ca5ebbb67fe",
"sha256": "54dd7e7edbef057a5f5cf8e87c79f5b31cc4763b368b6bf301c79d83de03db26"
},
"downloads": -1,
"filename": "mkdocs_semiliterate-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "76fbca8c15b33bb30e683ca5ebbb67fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15697,
"upload_time": "2024-11-02T19:32:25",
"upload_time_iso_8601": "2024-11-02T19:32:25.841684Z",
"url": "https://files.pythonhosted.org/packages/08/00/0cf88132042d7dedcab1ef138ce57ea79323d6a28c469d2db592edc7c912/mkdocs_semiliterate-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 19:32:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mkdocs-semiliterate"
}
JSON