Can we drop the "scenario" lines from the Navigation pages?

[cdemattio-jc]

When generating TOC/Navigation Pages, the tool includes "Scenario", "Scenario Outline", and "Examples" headings. For all but the most trivial system definitions, the number of those sub-headings will rapidly overwhelm the "Feature" headings. Should we drop the scenarios headings out of the TOC and Navigation Pages so that we can focus on the Features? If someone needs to see the specific tests, they can navigate into a Feature File.

Sorry, I can't attach a good example due to confidentiality issues.

@brolewis knows what I'm talking about.

[dgou]

Having just looked over this while doing a KT today, it was super helpful to be able to see the scenario summaries and get a nice overview.

If you just want the features, you have that in the navigation pane in the left already, right? I mean, left? 😁 I do agree that the example table headers aren’t adding much and would be fine losing those in the outline/toc view That said, I would be fine with adding a command line option for controlling the level of detail, but i don’t want to lose what i have now.

Semi related, i would like to lose the Feature and Scenario / Scenario Outline prefix text, that info is conveyed by the header size/fornatting already and those extra words just force the parts i care about further right. Have been too busy to open a PR for that so far, but since we’re talking formatting I thought I would mention it.

[dgou]

As to anything confidential, you got a version control system, right, so just do a quick sed on the feature and summary lines, generate the docs and git checkout to undo your changes. I think a screenshot would help a lot and should be pretty quick to generate.

[dgou]

So, for example, on the left I can open up a particular product's TOC and see all the Features, and on the right, I can see one layer down. And yeah, the Examples really don't add in anything. Of course, I don't know if this is the kind of structure you have without a screenshot of your stuff, and how many levels to show can also depend on what is "above" the part where feature files are injected into the toc(s).

[rbcasperson]

@dgou yeah our examples look basically exactly like that. I think there are a couple things we are looking to improve and a few ways to go about them.

We don't want to see the Scenarios and Examples on this page

The obvious solution to this is to change the --max-toc-depth amount, which we can do in both sphinx-gherkindoc and also in our manually created sphinx rst files.

Another option would be to change how Scenario is put into the rst file by this tool to make it so that would never be included in a TOC regardless of depth (don't put it as a header). I don't think that's the right approach for Scenario, but I do think that is the right approach for Examples as I can't think of a reason why it would useful to link to an example table section or see it in a TOC.

We don't want to see the Feature:, Scenario: and Scenario Outline: prefixes here.

I think that could be an easy implementation to just have a --no-prefixes flag, but is a separate feature from this issue.

[dgou]

I agree about Examples not needing to be in the TOC at all. I think solving that can be done as a night small chunk of work in service of this larger issue.

Ideally this larger issue would be something the user's browser would be able to control dynamically ... just as you can click on the navigation/TOC on the left to expose individual sub-elements of the TOC tree, it would be nice if you could fold/rollup unfold/unroll visible depth on the right dynamically, but I'm not willing to put in the time to make RTD "do that" :-)

Just playing around with building the sphinx_gherkindoc docs themselves, using -d 1 on the sphinx_gherkindoc command line gave me a right hand pane with just the features list, so I'm not sure that there is even an issue here? Just tweak your build command line. Of course, I'm very pre-coffee here, so I might be missing something or not seeing another side effect of that.

[rcasperson-jc]

@dgou I agree that the only action item from this would be to make it impossible to have the Examples table in TOC. Everything else is either too much of an ask for this tool (dropdowns in TOC) or something that can be handled by current functionality.

[cdemattio-jc]

@dgou , @rbcasperson , Agreed. Just removing the Examples and tweaking the TOC levels resulted in a much more pleasing view. I would kill for the expanding/collapsing TOC levels though. :)

Thanks for the input Doug!

[dgou]

Over 2.5 years later, I think this issue has aged out and can be closed @rbcasperson @cdemattio-jc ??