glen/mkdocs-semiliterate
1
0
Fork 0
Code Issues 1 Pull Requests Projects Releases 11 Wiki Activity
0.8.1
mkdocs-semiliterate/README.md

35 lines
3.1 KiB
Markdown
Raw Permalink Normal View History

feat: Add `extract_on_copy` option Previously, mkdocs_semiliterate would always attempt to extract documentation from a file, even if it matched the `include_extensions` pattern for files to be copied to the documentation site verbatim. Now, by default, such files are not considered candidates for extraction, even if they match a semiliterate pattern. Adds a configuration option `extract_on_copy` which can be set to `true` to restore the prior behavior. Also adds tests for the behavior with and without `extract_on_copy` and makes all `mkdocs build` commands in the tests strict, which they always should have been. Resolves #17.
2022-07-12 19:14:41 +00:00
# ![Dreaming of integrated documentation](assets/icons8-ask-question-100.png) MkDocs semiliterate Plugin
Initial commit
2021-01-08 04:10:06 +00:00
chore: Update to mkdocs-simple v2.1.2 (#23) Note the upstream refactor from mkdocs-simple v1 -> v2 was fairly large, so this is a rather larger update than most. And in fact one feature of mkdocs-semiliterate (universal markdown extraction) was incorporated into mkdocs-simple, so the initialization of this plugin is noticeably simplified as a result. Also updates mkdocs to 1.4. Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/23
2022-11-09 20:52:47 +00:00
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.
chore: Update to mkdocs-simple-plugin v1.0 Also updates from pep517.build to the `build` package, and bumps the semiliterate version number. Resolves #14.
2021-08-24 17:58:55 +00:00
<!-- repo: --><!-- site: The current version of mkdocs-semiliterate is {! setup.cfg { extract: {start: name}, terminate: '(\d*\.\d*\.\d*)', ensurelines: false} !}. -->
chore: Update to mkdocs-simple v2.1.2 (#23) Note the upstream refactor from mkdocs-simple v1 -> v2 was fairly large, so this is a rather larger update than most. And in fact one feature of mkdocs-semiliterate (universal markdown extraction) was incorporated into mkdocs-simple, so the initialization of this plugin is noticeably simplified as a result. Also updates mkdocs to 1.4. Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/23
2022-11-09 20:52:47 +00:00
<!-- repo: --><!-- site: It is built on mkdocs-simple-plugin v{! setup.cfg { extract: {start: 'mkdocs~=', stop: '(\d*\.\d*\.?\d*)'}, ensurelines: false} !}. -->
chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2021-01-08 06:39:40 +00:00
## Rationale
refactor: Build on top of released mkdocs-simple-plugin v0.4.0 (#8) Includes documentation updates, particularly for installation. Removes a now-duplicate parameter. Adds project metadata. Should be ready for release. Resolves #7. Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/8 Co-Authored-By: Glen Whitney <glen@nobody@nowhere.net> Co-Committed-By: Glen Whitney <glen@nobody@nowhere.net>
2021-02-09 06:26:39 +00:00
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.
chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2021-01-08 06:39:40 +00:00
*[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information.
docs: Prepare for PyPI publication (#10) Update installation instructions to reflect ability to use `pip`. Add concrete examples of extraction. Resolves #9. Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/10 Co-Authored-By: Glen Whitney <glen@nobody@nowhere.net> Co-Committed-By: Glen Whitney <glen@nobody@nowhere.net>
2021-02-09 17:47:02 +00:00
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.
chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2021-01-08 06:39:40 +00:00
chore: set up automated deployment Now, when one promotes a build in Drone to "release," the website should automatically be copied to studioinfinity.org
2021-01-10 04:13:01 +00:00
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.
chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2021-01-08 06:39:40 +00:00
docs: Prepare for PyPI publication (#10) Update installation instructions to reflect ability to use `pip`. Add concrete examples of extraction. Resolves #9. Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: https://code.studioinfinity.org/glen/mkdocs-semiliterate/pulls/10 Co-Authored-By: Glen Whitney <glen@nobody@nowhere.net> Co-Committed-By: Glen Whitney <glen@nobody@nowhere.net>
2021-02-09 17:47:02 +00:00
## 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`
feat: Add `extract_on_copy` option Previously, mkdocs_semiliterate would always attempt to extract documentation from a file, even if it matched the `include_extensions` pattern for files to be copied to the documentation site verbatim. Now, by default, such files are not considered candidates for extraction, even if they match a semiliterate pattern. Adds a configuration option `extract_on_copy` which can be set to `true` to restore the prior behavior. Also adds tests for the behavior with and without `extract_on_copy` and makes all `mkdocs build` commands in the tests strict, which they always should have been. Resolves #17.
2022-07-12 19:14:41 +00:00
## License and Acknowledgments
chore: initialize setuptools project Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2021-01-08 06:39:40 +00:00
feat: Add `extract_on_copy` option Previously, mkdocs_semiliterate would always attempt to extract documentation from a file, even if it matched the `include_extensions` pattern for files to be copied to the documentation site verbatim. Now, by default, such files are not considered candidates for extraction, even if they match a semiliterate pattern. Adds a configuration option `extract_on_copy` which can be set to `true` to restore the prior behavior. Also adds tests for the behavior with and without `extract_on_copy` and makes all `mkdocs build` commands in the tests strict, which they always should have been. Resolves #17.
2022-07-12 19:14:41 +00:00
This software is licensed under [Apache 2.0](LICENSE). [Icons8](https://icons8.com/icon/115368/ask-question) provided the icon.
Reference in New Issue Copy Permalink