feat: Implement double-quoted filename features. #13

Merged
glen merged 7 commits from quoted_filename into main 2021-02-12 17:11:07 +00:00
2 changed files with 58 additions and 12 deletions
Showing only changes of commit 42dd557ba7 - Show all commits

View File

@ -112,6 +112,47 @@ is checked for `{! ... !}`.
raise EOFError(errmsg) raise EOFError(errmsg)
filename = body_match['fn'] filename = body_match['fn']
gitextract = False gitextract = False
dq_doc = """ md
### Double-quoted filenames and Git extraction
Standard Python escape sequences in double-quoted filenames are interpreted
as usual; for example you can write
```
{! ../tests/fixtures/quoted-filename/README.md extract:
start: '(.*!.*)'
stop: '\s'
!}
```
to include a file whose name (`snippet/Say "Don't"`, in this case) has both
double and single quotes.
Further, `semiliterate` supports a special escape to extract a file from the
Git archive of the project (presuming it is under Git version control) and then
include content from that file. For example, you could write
```
{! ../tests/fixtures/git-inclusion/README.md extract:
start: '(.*!.*)'
stop: '\s'
!}
```
to extract content starting after the `### install` line from the
`mkdocs.yml` file in the Git commit of this repository
tagged `0.1.0`. This feature is primarily useful if you are documenting the
development or changes to a project over time, and want to be sure that
material included in your documentation does _not_ change as the project
progresses. (This behavior is as opposed to the usual case, in which you want
your documentation to incorporate the most up-to-date version of extracted
content.)
The precise behavior for a FILENAME argument in a `{! ... !}` inclusion of the
form
`"\git SPECIFIER"`
is that the output of `git show SPECIFIER` is written to a temporary file,
and that file is extracted from.
"""
if doublequoted: if doublequoted:
if filename[:5] == r'\git ': if filename[:5] == r'\git ':
gitextract = True gitextract = True
@ -151,10 +192,23 @@ is checked for `{! ... !}`.
class SemiliteratePlugin(SimplePlugin): class SemiliteratePlugin(SimplePlugin):
r""" md An extension of the mkdocs-simple-plugin r""" md An extension of the mkdocs-simple-plugin
In addition, block-comment markdown `/** md` ... `**/` is by ### Universal block-comment markdown
default scanned for in all files with _any_ extension, as it's valid in so many
disparate languages.
By default, `semiliterate` scans for block-comment markdown `/** md` ... `**/`
in all files with _any_ extension, as it's valid in so many disparate languages.
(As opposed to `simple`, which defaults to searching for such markdown in a
specific list of file types.)
"""
super_sdict = dict(SimplePlugin.config_scheme)
super_semi_dflt = super_sdict['semiliterate'].default
semi_dflt = [b if 'js' not in b['pattern'] else dict(b, pattern=r'\.')
for b in super_semi_dflt]
altered_config_scheme = dict(
super_sdict,
semiliterate=config_options.Type(list, default=semi_dflt)).items()
add_param_doc = r""" md
### Additional plugin parameters ### Additional plugin parameters
`semiliterate` adds a couple of new plugin parameters to further tailor its `semiliterate` adds a couple of new plugin parameters to further tailor its
@ -170,14 +224,6 @@ default values in parentheses at the beginning of each entry.
terminate: '^\s*\)' terminate: '^\s*\)'
!} !}
""" """
super_sdict = dict(SimplePlugin.config_scheme)
super_semi_dflt = super_sdict['semiliterate'].default
semi_dflt = [b if 'js' not in b['pattern'] else dict(b, pattern=r'\.')
for b in super_semi_dflt]
altered_config_scheme = dict(
super_sdict,
semiliterate=config_options.Type(list, default=semi_dflt)).items()
config_scheme = ( config_scheme = (
# Note documentation of each new parameter **follows** the parameter. # Note documentation of each new parameter **follows** the parameter.
*altered_config_scheme, *altered_config_scheme,

View File

@ -1,6 +1,6 @@
[metadata] [metadata]
name = mkdocs-semiliterate name = mkdocs-semiliterate
version = 0.1.1 version = 0.2.0
description = Extension of mkdocs-simple-plugin adding easy content inclusion description = Extension of mkdocs-simple-plugin adding easy content inclusion
long_description = file: README.md long_description = file: README.md
long_description_content_type = text/markdown long_description_content_type = text/markdown