sphinx_gherkindoc package

Bring Gherkin Goodness into the Sphinx/reStructuredText (rST) world.

Subpackages

Submodules

sphinx_gherkindoc.cli module

Module for running the tool from the CLI.

sphinx_gherkindoc.cli.config()[source]

Emit a customized version of the sample sphinx config file.

Return type

None

sphinx_gherkindoc.cli.main()[source]

Convert a directory-tree of Gherkin Feature files to rST files.

Return type

None

sphinx_gherkindoc.cli.process_args(args, gherkin_path, output_path, doc_project)[source]

Process the supplied CLI args.

Return type

None

sphinx_gherkindoc.files module

File-related utils used throughout the module.

class sphinx_gherkindoc.files.DirData(dir_path: pathlib.Path, path_list: List[str], sub_dirs: List[str], files: List[str])[source]

Bases: tuple

Named tuple containing all the modified os.walk parts for a given path.

Create new instance of DirData(dir_path, path_list, sub_dirs, files)

property dir_path

Alias for field number 0

property files

Alias for field number 3

property path_list

Alias for field number 1

property sub_dirs

Alias for field number 2

sphinx_gherkindoc.files.is_feature_file(filename)[source]

Determine if the given filename is a feature file.

Return type

bool

sphinx_gherkindoc.files.is_rst_file(filename)[source]

Determine if the given filename is a rST file.

Return type

bool

sphinx_gherkindoc.files.scan_tree(starting_point, private, exclude_patterns)[source]

Return list of entities to process, in top-down orders.

the list can easily be processed with .pop to get a bottom-up directory ordering.

Return type

List[DirData]

sphinx_gherkindoc.glossary module

Module specific to building the steps glossary.

class sphinx_gherkindoc.glossary.GlossaryEntry[source]

Bases: object

Track all the different places, and by which spellings, something is used.

add_reference(step_name, filename, line_number)[source]

Add a reference to the glossary.

Parameters

  • step_name (str) – The step name in Gherkin

  • filename (Path) – The file name containing the step

  • line_number (int) – The line number containing the step

Return type

None

tuple_len()[source]

Get the length for each location and the number of associated steps.

Return type

Tuple[int, int]

sphinx_gherkindoc.glossary.make_steps_glossary(project_name, group_by=False)[source]

Return SphinxWriter containing the step glossary information, if any.

Return type

Optional[SphinxWriter]

sphinx_gherkindoc.utils module

Generic utils used throughout the module.

class sphinx_gherkindoc.utils.SphinxWriter[source]

Bases: object

Easy Sphinx-format file creator.

add_output(line, line_breaks=1, indent_by=0)[source]

Add output to be written to file.

Parameters

  • line (str) – The line to be written

  • line_breaks (int) – The number of line breaks to include

  • indenty_by – The number of spaces to indent the line.

Return type

None

blank_line()[source]

Write a single blank line.

Return type

None

create_section(level, section)[source]

Create a reST-formatted section header based on the provided level.

Parameters

  • level (int) – The level depth of the section header (1-10 supported)

  • section (str) – The section title

Return type

None

sections = ['', '=', '-', '~', '.', '*', '+', '_', '<', '>', '/']
write_to_file(filename)[source]

Write the provided output to the given filename.

Parameters

filename (Path) – The full path to write the output

Return type

None

sphinx_gherkindoc.utils.display_name(path, package_name='', dir_display_name_converter=None)[source]

Create a human-readable name for a given project.

Determine the display name for a project given a path and (optional) package name. If a display_name.txt file is found, the first line is returned. Otherwise, return a title-cased string from either the base directory or package_name (if provided).

Parameters

  • path (Path) – Path for searching

  • package_name (Optional[str]) – Sphinx-style, dot-delimited package name (optional)

  • dir_display_name_converter (Optional[Callable]) – A function for converting a dir to a display name.

Return type

str

Returns

A display name for the provided path

sphinx_gherkindoc.utils.get_all_included_scenarios(feature, include_tags=None, exclude_tags=None)[source]

Get all scenarios to include in the docs based on the include/exclude tags.

This is designed to match what tests would be run if you ran a test suite with something like this (pytest-bdd format):

-m include_this_tag -m "not exclude_this_tag"
Parameters

  • feature (FeatureClass) – The feature whose scenarios are to be filtered.

  • include_tags (Optional[List[str]]) – Tags for which scenarios should be included.

  • exclude_tags (Optional[List[str]]) – Tags for which scenarios should be excluded.

Return type

List[ScenarioClass]

Returns

All scenarios to include.

sphinx_gherkindoc.utils.make_flat_name(path_list, filename_root=None, is_dir=False, ext='.rst')[source]

Build a flat file name from the provided information.

Parameters

  • path_list (List[str]) – Directory hierarchy to flatten

  • filename_root (Optional[str]) – If provided, the root of the filename to flatten (no extension)

  • is_dir (bool) – If True, mark the new filename as a table of contents

  • ext (Optional[str]) – Optional extension for the new file name

Return type

str

Returns

A filename containing the full path, separated by periods

sphinx_gherkindoc.utils.rst_escape(unescaped, slash_escape=False)[source]

Escape reST-ful characters to prevent parsing errors.

Parameters

  • unescaped (str) – A string that potentially contains characters needing escaping

  • slash_escape (bool) – if True, escape slashes found in unescaped

Return type

str

Returns

A string which has reST-ful characters appropriately escaped

sphinx_gherkindoc.utils.set_dry_run(value)[source]

Set the value for DRY_RUN outside this module.

Return type

None

sphinx_gherkindoc.utils.set_verbose(value)[source]

Set the value for VERBOSE outside this module.

Return type

None

sphinx_gherkindoc.utils.verbose(message)[source]

Print message only if VERBOSE, with a DRY_RUN prefix as appropriate.

Return type

None

sphinx_gherkindoc.writer module

Helper functions for writing rST files.

sphinx_gherkindoc.writer.apply_role(role, content)[source]

Wrap the given content string in the given role.

Return type

str

sphinx_gherkindoc.writer.feature_to_rst(source_path, root_path, feature_parser='behave', get_url_from_tag=None, get_url_from_step=None, integrate_background=False, background_step_format='{}', raw_descriptions=False, include_tags=None, exclude_tags=None)[source]

Return a SphinxWriter containing the rST for the given feature file.

Return type

Optional[SphinxWriter]

sphinx_gherkindoc.writer.role_name_from(s)[source]

Convert a string to a format that can be used as an rST role.

Return type

str

sphinx_gherkindoc.writer.toctree(path_list, subdirs, files, maxtocdepth, root_path, dir_display_name_converter=None)[source]

Return a SphinxWriter for one level of a directory tree.

Any rST files found at this level will have their content included in the TOC file instead of being referenced. This allows us to put content in the TOC file directly. The rST files that are included are expected to contain proper headers as well as content. If no rST files are included, a header is created using display_name.

NOTE: If there is more than one rST file present,

the order of their inclusion in the TOC is by filename sort order.

Return type

SphinxWriter