Theme: 

1. Usage

1.1. Maven plugin

Add cukedoctor-section-layout as a dependency in the Cukedoctor Maven Plugin configuration in your pom.xml:

<plugin>
  <groupId>com.github.cukedoctor</groupId>
  <artifactId>cukedoctor-maven-plugin</artifactId>
  <version>2.0</version>
  <executions>
    <execution>
      <goals>
        <goal>execute</goal>
      </goals>
      <phase>install</phase>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>com.github.cukedoctor</groupId>
      <artifactId>cukedoctor-section-layout</artifactId>
      <version>2.0</version>
    </dependency>
  </dependencies>
</plugin>

1.2. CLI

Add cukedoctor-section-layout.jar to your classpath:

java -jar cukedoctor-main.jar
  -cp "path/to/cukedoctor-section-layout.jar;."
  -o "target/document-one"
  -p "target/test-classes/json-output/one_passing_one_failing.json"
  -t "Living Documentation"
  -f html
  -numbered
  -hideSummarySection
  -hideScenarioKeyword
The separator used in the -cp argument may not be ";" on your OS.

1.3. SPI

Register the Cukedoctor Section Layout renderer implementations in your META-INF/services directory.

2. User-Defined Sections

Cukedoctor has some built-in Sections, such as the Summary and Features Sections.
User-Defined Sections allow you to provide your own grouping of Features, rather than include them in the built-in Features Section.
User-Defined Sections are included after the Summary and Introduction Sections, but before the Features Section.

2.1. Grouping Features in Sections

2.1.1. Assigning a Feature to a Section

Given

I have the Feature 

@section-Dinosaurs
Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as

Dinosaurs

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.1.2. Title and Preamble

A Feature tagged with a Section, containing a Scenario named 'Root' will be used as the Root of a Section. The name of this Feature will be used to render the Section’s name and the Feature’s description will be rendered immediately underneath.
You can use full AsciiDoc markup in a Feature’s description to provide as much of a preamble to the Section as you wish, or none at all. You can also provide other Scenarios in the Feature, which will be rendered as normal.

If multiple Roots are defined for a Section, the result is undefined.

Given

I have the Feature 

@section-Dinosaurs
@order-2
Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I have the Feature 

@section-Dinosaurs
@order-1
Feature: Dinosaurs: Reality or Myth?
As children, we all come to know and love these alleged ancient titans, but _did they ever really exist_?

  Scenario: Root

  Scenario: Their demise
  If they did once exist, how did they cease to?

    Given a big enough meteor
And

I have the Feature 

@section-Birds
@order-3
Feature: Birds: Descendents of Titans?

  Scenario: Root
And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as

[[Dinosaurs:-Reality-or-Myth?, Dinosaurs: Reality or Myth?]]

Dinosaurs: Reality or Myth?

As children, we all come to know and love these alleged ancient titans, but did they ever really exist?

Scenario: Their demise

If they did once exist, how did they cease to?

Given

a big enough meteor

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

[[Birds:-Descendents-of-Titans?, Birds: Descendents of Titans?]]

Birds: Descendents of Titans?

2.1.3. Ordering

Sections are ordered by their Features, which themselves are ordered using the @order- tag .
The built-in Features Section is always rendered after other sections, irrespective of `@order-' tags applied to Features therein.

Given

I have the Feature 

@order-1
Feature: Habitat

  Scenario: Tar Pits

    Given I do not mind getting mucky
And

I have the Feature 

@section-Anatomy
@order-100
Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I have the Feature 

@section-Behaviour
@order-10
Feature: Hunters

  Scenario: Tyranosaurus Rex

    Given I am the best hunter
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Behaviour

Hunters

Scenario: Tyranosaurus Rex

Given

I am the best hunter

Anatomy

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

Features

Habitat

Scenario: Tar Pits

Given

I do not mind getting mucky

2.1.4. Skipping

Sections where all assigned Features are marked with the tag @skipDocs will themselves be skipped.

Given

I have the Feature 

@section-Anatomy
Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I have the Feature 

@skipDocs
@section-Behaviour
Feature: Hunters

  Scenario: Tyranosaurus Rex

    Given I am the best hunter
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Anatomy

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.1.5. Appendices

A Section can be made into an Appendix by applying the @appendix tag.
Appendix Sections are rendered after the Features Section.
They are otherwise identical in behaviour to non-Appendix Sections (e.g. how they are ordered).

Given

I have the Feature 

Feature: Habitat

  Scenario: Tar Pits

    Given I do not mind getting mucky
And

I have the Feature 

@section-Anatomy
@appendix
Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I have the Feature 

@section-Behaviour
Feature: Hunters

  Scenario: Tyranosaurus Rex

    Given I am the best hunter
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Behaviour

Hunters

Scenario: Tyranosaurus Rex

Given

I am the best hunter

Features

Habitat

Scenario: Tar Pits

Given

I do not mind getting mucky

Anatomy

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.1.6. Glossary

A Feature will be rendered as a Glossary Section if it is tagged with the @glossary Feature tag.
Only a single Feature should be tagged with @glossary. The behaviour when multiple Features are tagged is undefined.

As per the AsciiDoc documentation, you must add the [glossary] style before the first definition. Cukedoctor will add the style to the title automatically.
Given

I have the Feature 

@glossary
Feature: My Glossary
 Below are definitions for term used throughout this book.

[glossary]
Dinosaur:: fictitious giant reptile of old
Carnivore:: an animal that feeds solely on other animals

  Scenario: Root
When

I convert the Feature

Then

it will be rendered as

My Glossary

Below are definitions for term used throughout this book.

Dinosaur

fictitious giant reptile of old

Carnivore

an animal that feeds solely on other animals

2.1.7. Bibliography

A Feature will be rendered as a Bibliography Section if it is tagged with the @bibliography Feature tag.
Only a single Feature should be tagged with @bibliography. The behaviour when multiple Features are tagged is undefined.

Given

I have the Feature 

@bibliography
Feature: My Bibliography
- [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.
- [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

  Scenario: Root
When

I convert the Feature

Then

it will be rendered as

My Bibliography

  • [] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

2.1.8. Index Catalog

A Feature will be rendered as an Index Catalog Section if it is tagged with the @index Feature tag.
Only a single Feature should be tagged with @index. The behaviour when multiple Features are tagged is undefined.

Given

I have the Feature 

@index
Feature: My Index

  Scenario: Root
When

I convert the Feature

Then

it will be rendered as

My Index

2.2. Subsections

2.2.1. Assigning a Feature to a Subsection

Features are assigned to Subsections using the @subsection- tag

Given

I have the Feature 

@section-Dinosaurs
@subsection-Behaviour
Feature: Eating Habits

  Scenario: Hunting
And

I have the Feature 

@section-Dinosaurs
@subsection-Appearance
Feature: Head Adornments

  Scenario: Frills
And

I have the Feature 

@subsection-Relatives
Feature: Direct descendents

  Scenario: Birds
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Dinosaurs

Behaviour

Eating Habits

Scenario: Hunting

Appearance

Head Adornments

Scenario: Frills

Features

Relatives

Direct descendents

Scenario: Birds

2.2.2. Title and Preamble

In the same manner as Sections, a Feature tagged with a Subsection, containing a Scenario named 'Root' will be used as the Root of the Subsection. The name of this Feature will be used to render the Subsection’s name and the Feature’s description will be rendered immediately underneath.
You can use full AsciiDoc markup in a Feature’s description to provide as much of a preamble to the Subsection as you wish, or none at all. You can also provide other Scenarios in the Feature, which will be rendered as normal.

If multiple Roots are defined for a Section, the result is undefined.

Given

I have the Feature 

@section-Dinosaurs
@subsection-HeadAdornments
Feature: Sonic Phenomenon

  Scenario: Parasaurolophus
And

I have the Feature 

@section-Dinosaurs
Feature: Dinosaurs: Reality or Myth?
As children, we all come to know and love these alleged ancient titans, but _did they ever really exist_?

  Scenario: Root
And

I have the Feature 

@section-Dinosaurs
@subsection-HeadAdornments
Feature: Head Adornments
Big ones, small ones...

  Scenario: Root
And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as

[[Dinosaurs:-Reality-or-Myth?, Dinosaurs: Reality or Myth?]]

Dinosaurs: Reality or Myth?

As children, we all come to know and love these alleged ancient titans, but did they ever really exist?

Head Adornments

Big ones, small ones…​

Sonic Phenomenon

Scenario: Parasaurolophus

2.2.3. Ordering

Subsections are ordered by their Features, which themselves are ordered using the @order- tag .

Given

I have the Feature 

@section-Dinosaurs
@subsection-HeadAdornments
@order-2
Feature: Sonic Phenomenon

  Scenario: Parasaurolophus
And

I have the Feature 

@section-Dinosaurs
@subsection-Behaviour
@order-1
Feature: Hunters

  Scenario: Tyranosaurus Rex
And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as

Dinosaurs

Behaviour

Hunters

Scenario: Tyranosaurus Rex

HeadAdornments

Sonic Phenomenon

Scenario: Parasaurolophus

2.2.4. Skipping

Subsections where all assigned Features are marked with the tag @skipDocs will themselves be skipped.

Given

I have the Feature 

@skipDocs
@section-Dinosaurs
@subsection-Behaviour
@order-2
Feature: Foragers

  Scenario: Diplodocus
And

I have the Feature 

@skipDocs
@section-Dinosaurs
@subsection-Behaviour
@order-1
Feature: Hunters

  Scenario: Tyranosaurus Rex
And

I have the Feature 

@section-Dinosaurs
@subsection-Flavour
@order-3
Feature: Modern References

  Scenario: Chicken
And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as

Dinosaurs

Flavour

Modern References

Scenario: Chicken

2.3. Features not assigned to Sections

Features not assigned to Sections are rendered exactly as in the classic (default) Cukedoctor layout, with all its capabilities supported.

2.3.1. The built-in Features Section

If the Features Section is enabled, Features will be rendered by default in the Features Section unless otherwise assigned.

Given

I have the Feature 

Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as a Subsection of the Features Section

Features

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.3.2. When the Features Section is hidden

If the Features Section is hidden, each Feature not assigned to a Section will be rendered as a Section of its own.

Given

I have the Feature 

Feature: Head Adornments

  Scenario: Parasaurolophus

    Given I have an implausible head adornment
And

I am hiding the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

it will be rendered as a Section

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.3.3. Ordering

Features not assigned to Sections are ordered by their @order- tag
NOTE: If Features do not have an @order- tag, their order is not guaranteed.

Given

I have the Feature 

@order-2
Feature: Head Adornments

Scenario: Parasaurolophus

  Given I have an implausible head adornment
And

I have the Feature 

@order-1
Feature: Hunters

Scenario: Tyranosaurus Rex

  Given I am the best hunter
And

I am hiding the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Hunters

Scenario: Tyranosaurus Rex

Given

I am the best hunter

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment

2.3.4. Subsections

Features assigned to Subsections, but not Sections, will be shown under Subsections under the built-in Features Section.

Given

I have the Feature 

@order-2
@subsection-Appearance
Feature: Head Adornments

Scenario: Parasaurolophus

  Given I have an implausible head adornment
And

I am showing the Features Section

And

I am hiding step timings

And

all Cukedoctor extensions are disabled

When

I convert the Feature

Then

they will be rendered as

Features

Appearance

Head Adornments

Scenario: Parasaurolophus

Given

I have an implausible head adornment