A MkDocs plugin to render behave feature files
Project description
MkDocs Behave Plugin
A MkDocs plugin to render behave feature files.
Installation
pip install mkdocs-behave
Usage
Add the following to mkdocs.yml
:
plugins:
- behave
Feature files in features/
in the project root will be converted to Markdown
and included in MkDocs navigation under the heading Features
.
Live preview
While previewing documentation using mkdocs serve
, feature files will be
watched for changes in the same manner as Markdown files under docs/
Markdown in feature files
Markdown can be used in the description text of features. However, behave does not preserve leading whitespace in descriptions.
To protect Markdown in descriptions, prepend dots to a block:
Feature: My feature
. - A multi-level list
. - with indentation
. - that would otherwise be lost
Scenario: ...
Specifically, the following are stripped at the beginning of a line of description before it is processed as Markdown:
- A dot followed by a space
- A dot followed by a newline (i.e. no further text)
(Leading whitespace before the dots is stripped by behave)
Configuration
Configuration options can be set beneath the plugin entry in mkdocs.yml
.
plugins:
- behave:
<option>: <value>
# ...
The following options are available:
Option | Default | Effect |
---|---|---|
features_dir |
features |
Where feature files are read from disk (relative to the project root) |
nav_heading |
Features |
The top-level MkDocs navigation heading under which features are displayed |
populate |
true |
Whether to automatically populate features under nav_heading |
warn_missing |
true |
Whether to warn about features on disk that are not present in navigation |
step_highlight |
{} |
A mapping of regexp:language to syntax highlight step text based on the step name |
Example of syntax highlighting configuration:
plugins:
- behave:
step_highlight: {
'file named ".*\.py"': python,
'webpage containing': html,
}
Modes of operation
1. Fully automatic feature population
This is the default. All feature files are populated into the navigation, sorted alphanumerically.
Subdirectories under the features directory are turned into subheadings under the main navigation heading. Directory names are processed as follows:
- Underscores (_) are replaced with spaces
- The first character is capitalised
2. Partly manual feature population
To explicitly order features and subheadings, add suitable entries into
the navigation in mkdocs.yml
. You can also insert additional Markdown files.
nav:
- Features:
- features/index.md
- features/first.feature
- Sub heading:
- features/sub_heading/second.feature
- ...
Note that in this example, features/index.md
is read from under docs
as
normal, but the entries ending in .feature
are read from the features
directory in the project root.
Any features that are not explicitly listed in the expected heading are populated at the end of the heading.
To control the placement of the top-level features heading without otherwise adjusting its contents, insert it into the navigation as a blank heading:
nav:
- A heading:
- ...
- Features: []
- Another heading:
- ...
3. Fully manual feature population
Set populate: false
to lay out features in the navigation entirely manually.
A warning will be issued if feature files present on disk are missing from the
navigation, mirroring the behaviour of MkDocs for Markdown files.
To disable this and allow only a subset of features to be included, set
warn_missing: false
Licence
mkdocs-behave
is distributed under the terms of the MIT licence.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_behave-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b286b5ef79a0e126865f58076f238362f293b599ab2136a6259e77fe14e1e499 |
|
MD5 | 0a44bfbf9fd42e9767bbb4073e3aa0eb |
|
BLAKE2b-256 | 3e33ad12438f0ab57b135e452bd2d0de81d578dc8a6d9f3e7f91fdf9b83f5f43 |