diff --git a/.drone.yml b/.drone.yml
new file mode 100644
index 0000000..a2001de
--- /dev/null
+++ b/.drone.yml
@@ -0,0 +1,90 @@
+---
+### develop
+# ## Developing
+#
+# You can clone the repository with
+# ```
+# git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate
+# ```
+###
+kind: pipeline
+name: bootstrap
+steps:
+ - name: build_install_test
+ image: python
+ commands:
+ - 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:
+# ```
+# git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate
+# cd mkdocs-semiliterate
+# pip install .
+# ```
+###
+ - cd ../src
+### develop
+# You can build the distribution with
+# ```
+ - pip install pep517
+ - python -m pep517.build .
+# ```
+# That will produce a `.whl` file in the `dist` subdirectory.
+###
+ - pip install dist/mkdocs_semiliterate*.whl
+### develop
+# ### Testing
+#
+# If you have a a Docker daemon running on your local machine and the Drone
+# [command-line](https://readme.drone.io/cli/install) installed, you can run all
+# of the tests via `drone exec`. If not, or if you don't want to wait for the
+# Docker container to spin up and install all of the prerequisites, you can make
+# sure you have the version of mkdocs-semiliterate that you want to test
+# currently properly installed in the python you are currently running, and then
+# starting from the top-level `mkdocs-semiliterate` directory, run the commands
+# that drone uses to test:
+# ```
+ - flake8 --max-line-length=80 --extend-exclude=build
+ - mkdocs build
+ - find site -not -path '*fonts*' -not -path '*img*' -not -path '*js*' | sort -f | diff tests/bootstrap.manifest -
+ - cd tests/fixtures/recursive-inclusion
+ - mkdocs build
+ # unfortunately MkDocs writes the run date in the last few lines of index:
+ - head -n -3 site/index.html > site/croppedindex.html
+ - rm site/index.html
+ - diff -r -x img -x fonts -x js -x '*.gz' refsite site
+# ```
+# All of the commands should succeed and none of the diffs should produce any
+# output.
+###
+ - rm -r site
+ - name: validate
+ image: klakegg/html-proofer:latest
+ volumes:
+ - site: /src
+ command: ['--url-ignore', 'https://fonts.gstatic.com', '--allow-hash-href',
+ '--file-ignore', './site/404.html,/.*tests.*/']
+
+### develop
+# ### Contributing
+#
+# You can report issues at the
+# [repository site](https://code.studioinfinity.org/glen/mkdocs-semiliterate).
+# Pull requests are welcome as well. If you're new to contributing to open-source
+# projects, `mkdocs-simple-plugin` has a very nice
+# [tutorial](https://athackst.github.io/mkdocs-simple-plugin/CONTRIBUTING/).
+###
diff --git a/README.md b/README.md
index c9d968b..e0c2da7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# 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 usability tweaks).
+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).
## Rationale
@@ -12,10 +12,6 @@ The mkdocs-simple-plugin goes a long way toward creating a semiliterate programm
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. The 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).
diff --git a/mkdocs.yml b/mkdocs.yml
index 7b1e9df..49cb8f4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,12 +1,14 @@
site_name: MkDocs semiliterate plugin
nav:
- Overview: README.md
+- Installation: drone_install.md
- Usage: mkdocs_semiliterate/plugin.md
+- Developing: drone_develop.md
plugins:
- search
- semiliterate:
merge_docs_dir: false
- ignore_folders: [dist, build]
+ ignore_folders: [build, dist, tests]
include_extensions: [LICENSE]
semiliterate:
- pattern: '(\.md)$'
@@ -15,6 +17,16 @@ plugins:
- pattern: '(\.py)$'
start: '"""\smd'
stop: '"""'
+ - pattern: '.drone.yml'
+ destination: 'drone_develop.md'
+ start: '### develop'
+ stop: '^\s*###'
+ replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
+ - pattern: '.drone.yml'
+ destination: 'drone_install.md'
+ start: '### install'
+ stop: '^\s*###'
+ replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']
markdown_extensions:
- abbr
- def_list
diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py
index 384e362..bdc3829 100644
--- a/mkdocs_semiliterate/plugin.py
+++ b/mkdocs_semiliterate/plugin.py
@@ -1,11 +1,11 @@
""" md
## Usage
-Once this plugin is [installed](../README.md#installation), in your `mkdocs.yml`
+Once this plugin is [installed](../drone_install.md), in your `mkdocs.yml`
file just replace the plugin name `simple` with `semiliterate`. It accepts all
of the same parameters, so `mkdocs` will still work as before, and
-you will have immediate access to all of the following extensions. (Note that this
-documentation assumes a familiarity with the
+you will have immediate access to all of the following extensions. (Note that
+this documentation assumes a familiarity with the
[usage](https://athackst.github.io/mkdocs-simple-plugin/mkdocs_simple_plugin/plugin/)
of the `simple` plugin.)
"""
@@ -45,7 +45,7 @@ normally copy. That is, it does not examine lines before the `start` regexp
is encountered, or after the `terminate` regexp, or between instances of
`stop` and `start`. It also doesn't check any text written from lines that
match these special expressions. Moreover, on such normally-transcribed lines,
-it's the text **after** the application of any semiliterate replacements that
+it's the text **after** the application of any semiliterate `replace`ments that
is checked for `{! ... !}`.
"""
@@ -92,11 +92,11 @@ is checked for `{! ... !}`.
class SemiliteratePlugin(SimplePlugin):
- """ md An extension of the mkdocs-simple-plugin
+ r""" md An extension of the mkdocs-simple-plugin
### Additional plugin parameters
`semiliterate` adds a couple of new plugin parameters to further tailor its
-behavior as compared to `simple`. They are described in this section, with their
+behavior as compared to `simple`. They are described in this section, with
default values in parentheses at the beginning of each entry.
{! plugin.py ---
@@ -122,14 +122,14 @@ extract_standard_markdown
# because of the `extract_standard_markdown` default.
)
- def copy_doc_files(self, destination_directory):
+ def build_docs(self):
if not self.config['copy_standard_markdown']:
self.include_extensions = self.config['include_extensions']
- return super().copy_doc_files(destination_directory)
+ return super().build_docs()
- ## FIXME: This method is copied from simple, just to insert a control
- ## over what class is used to do the extraction. Try to get this inserted as
- ## the method of the same name in simple.
+ # FIXME: This method is copied from simple, just to insert a control
+ # over what class is used to do the extraction. Try to get this inserted as
+ # the method of the same name in simple.
def extract_from(self, from_directory, name, destination_directory):
"""Extract content from the file in _from_directory_ named _name_
to a file or files in _destination_directory_, as specified by
@@ -140,15 +140,22 @@ extract_standard_markdown
for item in self.semiliterate:
name_match = item['pattern'].search(name)
if name_match:
- new_name = (name[:name_match.start(name_match.lastindex)]
- + '.md'
- + name[name_match.end(name_match.lastindex):])
+ new_name = ''
+ if name_match.lastindex:
+ new_name = (name[:name_match.start(name_match.lastindex)]
+ + '.md'
+ + name[name_match.end(name_match.lastindex):])
if 'destination' in item:
new_name = name_match.expand(item['destination'])
+ if not new_name:
+ raise LookupError(
+ "mkdocs-simple-plugin: No last group in match of"
+ + "{} to {} and no destination".format(
+ item['pattern'], name))
new_file = LazyFile(destination_directory, new_name)
with open(original) as original_file:
utils.log.debug(
- "mkdocs-simple-plugin: Scanning {} ...".format(original))
+ "mkdocs-simple-plugin: Scanning {}...".format(original))
productive = self.try_extraction(
original_file, from_directory, new_file, **item)
new_file.close()
diff --git a/setup.cfg b/setup.cfg
index fb6938e..c43a2af 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
[metadata]
name = mkdocs-semiliterate
-version = 0.0.4
+version = 0.0.5
[options]
packages = mkdocs_semiliterate
diff --git a/tests/fixtures/recursive-inclusion/README.md b/tests/fixtures/recursive-inclusion/README.md
new file mode 100644
index 0000000..59e7c0f
--- /dev/null
+++ b/tests/fixtures/recursive-inclusion/README.md
@@ -0,0 +1,3 @@
+# More complex semiliterate site
+
+This site will involve custom extraction and inclusion.
diff --git a/tests/fixtures/recursive-inclusion/baz.qux b/tests/fixtures/recursive-inclusion/baz.qux
new file mode 100644
index 0000000..2ee818c
--- /dev/null
+++ b/tests/fixtures/recursive-inclusion/baz.qux
@@ -0,0 +1,9 @@
+I'd like you to know that
+really just about anything can go up here.
+START right here, because everything else on this line is ignored:
+| file
+ in{! xyzzy start: '(.*)' !}ion
+STOP that distraction!
+Now we can get back to our originally
+scheduled qux.
+Thanks very much!
diff --git a/tests/fixtures/recursive-inclusion/foo.bar b/tests/fixtures/recursive-inclusion/foo.bar
new file mode 100644
index 0000000..7045796
--- /dev/null
+++ b/tests/fixtures/recursive-inclusion/foo.bar
@@ -0,0 +1,27 @@
+Description: This is a hypothetical file of the bar language
+Explanation: It doesn't really make sense
+---
+## Exposition
+
+However, we can use it to test custom extraction
+---
+
+Information: This is a supposed "source code" section.
+Point: This should be ignored by semiliterate extraction.
+
+---
+And other features, such as extraction resumption.
+
+Not to mention{! baz.qux start: START
+terminate: STOP
+replace: ['^\|(.*)$'] !}syntax and `{! escaped syntax !}`.
+---
+
+Unfortunate: the bar language has no real structure
+
+!!!
+
+---
+But at least this stuff down here will go ignored
+
+
diff --git a/tests/fixtures/recursive-inclusion/foo.grepout b/tests/fixtures/recursive-inclusion/foo.grepout
new file mode 100644
index 0000000..6d8e35d
--- /dev/null
+++ b/tests/fixtures/recursive-inclusion/foo.grepout
@@ -0,0 +1,5 @@
+
However, we can use it to test custom extraction
+And other features, such as extraction resumption.
+
Not to mention file inclusion
+syntax and {! escaped syntax !}.