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.
This commit is contained in:
Glen Whitney 2021-01-07 22:39:40 -08:00
parent 6004ed0c0f
commit ec9c7e57ce
6 changed files with 76 additions and 2 deletions

3
.gitignore vendored
View File

@ -1,3 +1,6 @@
# Backups
*~
# ---> Python
# Byte-compiled / optimized / DLL files
__pycache__/

View File

@ -1,3 +1,21 @@
# mkdocs-semiliterate
# MkDocs semiliterate Plugin
An extension of the mkdocs-simple-plugin that adds syntax for including content from other files
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 usability tweaks).
## 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 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.
With a few other small ease-of-use tweaks (documented in the Usage section), this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. <!-- repo: -->The<!-- site:This --> documentation site is, of course, produced by MkDocs using the semiliterate plugin.
## Installation
To be written.
## License
This software is licensed under [Apache 2.0](LICENSE).

18
mkdocs.yml Normal file
View File

@ -0,0 +1,18 @@
site_name: MkDocs semiliterate plugin
nav:
- Overview: README.md
- Usage: mkdocs_semiliterate/plugin.md
plugins:
- search
- semiliterate:
merge_docs_dir: false
ignore_folders: [dist]
include_extensions: [LICENSE]
# semiliterate:
# - pattern: '(\.md)$'
# replace: [['^(.*)<!-- repo: -->.*<!-- site:(.*?) -->(.*\s*)$', '\1\2\3']]
markdown_extensions:
- abbr
theme:
name: readthedocs
docs_dir: mkdocs_semiliterate # dummy

View File

@ -0,0 +1,19 @@
""" md
## Usage
Once this plugin is [installed](../README.md#installation), in your `mkdocs.yml`
file just replace the plugin name `simple` with `semiliterate`. It accepts all
of the same parameters as `simple`, so `mkdocs` will still work as before, and
you will have immediate access to all of the following extensions:
### Inclusion syntax
To be documented when implemented.
"""
import mkdocs
from mkdocs.config import config_options
from mkdocs_simple_plugin.plugin import SimplePlugin
class SemiliteratePlugin(SimplePlugin):
""" So far, just an alias for simple """

3
pyproject.toml Normal file
View File

@ -0,0 +1,3 @@
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

13
setup.cfg Normal file
View File

@ -0,0 +1,13 @@
[metadata]
name = mkdocs-semiliterate
version = 0.0.1
[options]
packages = mkdocs_semiliterate
install_requires =
mkdocs
mkdocs-simple-plugin
[options.entry_points]
mkdocs.plugins =
semiliterate = mkdocs_semiliterate.plugin:SemiliteratePlugin