diff --git a/.drone.yml b/.drone.yml index 462e502..450b451 100644 --- a/.drone.yml +++ b/.drone.yml @@ -16,27 +16,17 @@ steps: - python --version - pwd - pip install flake8 - - cd .. ### install # ## Installation # -# At the moment, `semiliterate` relies on the latest pre-release version of -# `mkdocs-simple-plugin`. Therefore, you must clone and install that repository -# before installing `semiliterate`. -# ``` - - git clone https://github.com/athackst/mkdocs-simple-plugin.git - - cd mkdocs-simple-plugin - - pip install . -# ``` -# Once that's in place, you can install semiliterate; right now as there has -# not yet been a release, you should do that by cloning and installing as well: +# Since there has not yet been a release of mkdocs-semiliterate, +# you should install it by cloning the repository: # ``` # git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate # cd mkdocs-semiliterate # pip install . # ``` ### - - cd ../src ### develop # You can build the distribution with # ``` 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/__init__.py b/mkdocs_semiliterate/__init__.py new file mode 100644 index 0000000..413fa9c --- /dev/null +++ b/mkdocs_semiliterate/__init__.py @@ -0,0 +1 @@ +"""mkdocs_semiliterate package.""" 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..6c93959 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,12 +1,30 @@ [metadata] name = mkdocs-semiliterate -version = 0.0.12 +version = 0.1.0 +description = Extension of mkdocs-simple-plugin adding easy content inclusion +long_description = file: README.md +long_description_content_type = text/markdown +keywords = mkdocs literate +url = http://studioinfinity.org/semiliterate +project_urls = + Issues = https://code.studioinfinity.org/glen/mkdocs-semiliterate/issues, + Documentation = http://studioinfinity.org/semiliterate, + Source Code = http://code.studioinfinity.org/glen/mkdocs-semiliterate +author = Glen Whitney +author_email = glen@studioinfinity.org +classifiers = + Development Status :: 4 - Beta + Intended Audience :: Developers + Intended Audience :: Information Technology + Programming Language :: Python + Programming Language :: Python :: 3 :: Only +license = Apache-2.0 [options] packages = mkdocs_semiliterate install_requires = mkdocs - mkdocs-simple-plugin + mkdocs-simple-plugin>=0.4.0 [options.entry_points] mkdocs.plugins =