| Name | mkdocs-behave JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A MkDocs plugin to render behave feature files |
| upload_time | 2023-12-02 18:23:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MkDocs Behave Plugin
[](https://pypi.org/project/mkdocs-behave)
[](https://pypi.org/project/mkdocs-behave)
A [MkDocs](https://www.mkdocs.org/) plugin to render [behave](https://behave.readthedocs.io/) feature files.
## Installation
```console
pip install mkdocs-behave
```
## Usage
Add the following to `mkdocs.yml`:
```yaml
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:
```gherkin
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`.
```yaml
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:
```yaml
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.
```yaml
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:
```yaml
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](https://spdx.org/licenses/MIT.html) licence.
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-behave",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Matthew Francis <mjay.francis@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ac/c2/51113ab8b288b10e2de972f06a722d600bdc3eaa321a7c6ce3144f926fe0/mkdocs_behave-1.0.0.tar.gz",
"platform": null,
"description": "# MkDocs Behave Plugin\n\n[](https://pypi.org/project/mkdocs-behave)\n[](https://pypi.org/project/mkdocs-behave)\n\nA [MkDocs](https://www.mkdocs.org/) plugin to render [behave](https://behave.readthedocs.io/) feature files.\n\n## Installation\n\n```console\npip install mkdocs-behave\n```\n\n## Usage\n\nAdd the following to `mkdocs.yml`:\n```yaml\nplugins:\n - behave\n```\n\nFeature files in `features/` in the project root will be converted to Markdown\nand included in MkDocs navigation under the heading `Features`.\n\n### Live preview\n\nWhile previewing documentation using `mkdocs serve`, feature files will be\nwatched for changes in the same manner as Markdown files under `docs/`\n\n### Markdown in feature files\n\nMarkdown can be used in the description text of features. However, behave does\nnot preserve leading whitespace in descriptions.\n\nTo protect Markdown in descriptions, prepend dots to a block:\n\n```gherkin\nFeature: My feature\n\n . - A multi-level list\n . - with indentation\n . - that would otherwise be lost\n\nScenario: ...\n```\n\nSpecifically, the following are stripped at the beginning of a line of\ndescription before it is processed as Markdown:\n- A dot followed by a space\n- A dot followed by a newline (i.e. no further text)\n\n(Leading whitespace before the dots is stripped by behave)\n\n### Configuration\n\nConfiguration options can be set beneath the plugin entry in `mkdocs.yml`.\n\n```yaml\nplugins:\n - behave:\n <option>: <value>\n # ...\n```\n\nThe following options are available:\n\n| Option | Default | Effect |\n|------------------|------------|-------------------------------------------------------------------------------------|\n| `features_dir` | `features` | Where feature files are read from disk (relative to the project root) |\n| `nav_heading` | `Features` | The top-level MkDocs navigation heading under which features are displayed |\n| `populate` | `true` | Whether to automatically populate features under `nav_heading` |\n| `warn_missing` | `true` | Whether to warn about features on disk that are not present in navigation |\n| `step_highlight` | `{}` | A mapping of `regexp:language` to syntax highlight step text based on the step name |\n\nExample of syntax highlighting configuration:\n```yaml\nplugins:\n - behave:\n step_highlight: {\n 'file named \".*\\.py\"': python,\n 'webpage containing': html,\n }\n```\n\n### Modes of operation\n\n#### 1. Fully automatic feature population\n\nThis is the default. All feature files are populated into the navigation, sorted\nalphanumerically.\n\nSubdirectories under the features directory are turned into subheadings under\nthe main navigation heading. Directory names are processed as follows:\n- Underscores (_) are replaced with spaces\n- The first character is capitalised\n\n#### 2. Partly manual feature population\n\nTo explicitly order features and subheadings, add suitable entries into\nthe navigation in `mkdocs.yml`. You can also insert additional Markdown files.\n\n```yaml\nnav:\n - Features:\n - features/index.md\n - features/first.feature\n - Sub heading:\n - features/sub_heading/second.feature\n - ...\n```\n\nNote that in this example, `features/index.md` is read from under `docs` as\nnormal, but the entries ending in `.feature` are read from the `features`\ndirectory in the project root.\n\nAny features that are not explicitly listed in the expected heading are\npopulated at the end of the heading.\n\nTo control the placement of the top-level features heading without otherwise adjusting\nits contents, insert it into the navigation as a blank heading:\n```yaml\nnav:\n - A heading:\n - ...\n - Features: []\n - Another heading:\n - ...\n```\n\n#### 3. Fully manual feature population\n\nSet `populate: false` to lay out features in the navigation entirely manually.\nA warning will be issued if feature files present on disk are missing from the\nnavigation, mirroring the behaviour of MkDocs for Markdown files.\n\nTo disable this and allow only a subset of features to be included, set\n`warn_missing: false`\n\n\n## Licence\n\n`mkdocs-behave` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) licence.\n",
"bugtrack_url": null,
"license": null,
"summary": "A MkDocs plugin to render behave feature files",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/mjayfrancis/mkdocs-behave#readme",
"Issues": "https://github.com/mjayfrancis/mkdocs-behave/issues",
"Source": "https://github.com/mjayfrancis/mkdocs-behave"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e33ad12438f0ab57b135e452bd2d0de81d578dc8a6d9f3e7f91fdf9b83f5f43",
"md5": "0a44bfbf9fd42e9767bbb4073e3aa0eb",
"sha256": "b286b5ef79a0e126865f58076f238362f293b599ab2136a6259e77fe14e1e499"
},
"downloads": -1,
"filename": "mkdocs_behave-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a44bfbf9fd42e9767bbb4073e3aa0eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8967,
"upload_time": "2023-12-02T18:23:46",
"upload_time_iso_8601": "2023-12-02T18:23:46.243805Z",
"url": "https://files.pythonhosted.org/packages/3e/33/ad12438f0ab57b135e452bd2d0de81d578dc8a6d9f3e7f91fdf9b83f5f43/mkdocs_behave-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "acc251113ab8b288b10e2de972f06a722d600bdc3eaa321a7c6ce3144f926fe0",
"md5": "52bc1b61317e61aa763fc10d826172c7",
"sha256": "b75e4e6530f95d49066f951554ab50268cbb8c23af482eff15b226c81ff05975"
},
"downloads": -1,
"filename": "mkdocs_behave-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "52bc1b61317e61aa763fc10d826172c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7658,
"upload_time": "2023-12-02T18:23:47",
"upload_time_iso_8601": "2023-12-02T18:23:47.626771Z",
"url": "https://files.pythonhosted.org/packages/ac/c2/51113ab8b288b10e2de972f06a722d600bdc3eaa321a7c6ce3144f926fe0/mkdocs_behave-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-02 18:23:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mjayfrancis",
"github_project": "mkdocs-behave#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-behave"
}
