search

jolly-good-toolbelt / sphinx_gherkindoc

A tool to convert Gherkin into Sphinx documentation
https://jolly-good-toolbelt.github.io/sphinx_gherkindoc/
11 stars 10 forks source link

Enhancement: Build docs for subsets of features/scenarios based on tags #40

Closed rbcasperson closed 4 years ago

rbcasperson commented 4 years ago

What & Why

A new feature! Hopefully the docs and tests are clear enough to describe the behavior, but here's what it is, and why it can be useful:

This change let's you build documentation for only a subset of your feature files, based on tags. You can provide include tags for only including features/scenarios with those tags, and exclude tags for excluding features/scenarios with those tags.

This is particularly useful for part of my workflow because we want to use sphinx-gherkindoc to show all of the tests from a specific test run. Like if a test run passes, look here to see the coverage of all the behavior that has been validated. So in that case, we would exclude tests that were skipped or expected to fail. sphinx-gherkindoc makes it nice to look at a group of features/scenarios, so it can also make it nice to look at a specific subset of features/scenarios.

Implementation/Review Notes

The thing that complicated this the most was scenario examples tables. Since examples tables can be tagged, you want to filter those out as well. So an include tag could be on the feature, scenarios, or only the examples table, and that should be included.

There were a bunch of cases I tried to think about. I did a true TDD style where I wrote out all the test cases to describe the behavior expectations and then implemented to make that work. Besides looking at the source code itself, reviewing the test cases for possible missing edge cases will be great. pytest does show that the code coverage for that logic is 100% but that doesn't mean there isn't code that should be there to handle a special case.

The logic is pretty long and possibly confusing (even for me having written it). I tried to refactor as best I could to organize it in the last commit, but I'm definitely happy to get suggestions for how it could be cleaner.

dgou commented 4 years ago

Reviewer note to self: Built this on my work repo and got the same results as with 3.4.6 -- need to look at changes in detail.

sdutton-personal commented 4 years ago

Huh, seems as though checks are still running? Not sure what the deal is there.

rbcasperson commented 4 years ago

Yeah that's weird. I'll take a look.

rbcasperson commented 4 years ago

I just reset the last commit hash and repushed and it looks like CI triggered 🤷