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

Allow for dynamic display names based on dir names #22

Closed rbcasperson closed 4 years ago

rbcasperson commented 4 years ago

This is an interesting idea that I think will be useful!

display_name.txt is a great feature. Lets you make the docs titles look nice. But what if there is a pattern you want to follow based on the directory name? You can currently manually create a display_name.txt file in every directory, but then you have to remember to do that every time new directories are added.

This PR proposes a solution where you pass in a module/function pair that will translate directory names into display names. It works the same way that the --url-from-tag flag works, and it expects the value to be in the same format.

NOTE: There's weren't any unit tests for the --url-from-tag flag (see the code coverage). That isn't necessarily an excuse to not add them here, but perhaps it can be a FF to add tests for both. Either way I wanted to get this idea out there for early feedback, and I'll look into adding the tests nonetheless.

For context, we have our features dir structure match the API we are testing, and we want the docs to look like the actual url. So I have it pointing a helper that changes dir names to f"/{dir_name}", and puts curly braces around URL params. This makes it easier to see how the features in the structure matches the URL (the tests are really low level, so it makes sense to care about exactly which URL).

rbcasperson commented 4 years ago

Thanks @dgou, yeah I can certainly add an example on how to use it.

rbcasperson commented 4 years ago

When I was going to add documentation about the new flag, I realized that to keep it in line with the -url-from-tag flag, it should also support the parsers option. That allowed me to consolidate the documentation for both, but I had to add support for the parsers option, which also required some refactoring.

bradsbrown commented 4 years ago

NB thoughts after looking over this code:

dgou commented 4 years ago

After today's adventure, I think I want to pull this PR tomorrow and run it against my SNBN repo and make sure it's good, and re-re-review with fresh eyes in the AM.

rbcasperson commented 4 years ago

Thanks for the thoughts @bradsbrown. I agree that there is probably a nicer way to handle this. And it can probably apply to the url from tag logic as well. I already have one FF for this PR, so let me consider that as well.