From 4a31e5a9ab7b5ccb1e9c153377076d522d1633f7 Mon Sep 17 00:00:00 2001
From: jenisys <jenisys@users.noreply.github.com>
Date: Tue, 22 Mar 2016 21:56:48 +0100
Subject: [PATCH 2/3] Add step-label to be used in step-refs, like:   # --
 FILE: something.rst   See also :ref:`When I create a database
 "{db_server}:{db_name}"`

NOTES:
* Step-labels are just before heading.
* docutils must be installed to use them.

(cherry picked from commit d3f7a2ac99c6f7faae331b05f56096eb851d11c9)
---
 CHANGES.rst                      |  3 +++
 behave/formatter/sphinx_steps.py | 29 ++++++++++++++++++++++-------
 behave/formatter/sphinx_util.py  |  4 +++-
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 1bdb644..e32d2b6 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -8,6 +8,9 @@ GOALS:
 
   - Improve support for Windows
 
+FORMATTERS:
+
+  * pull #423: sphinx.steps: Support ref link for each step (provided by: ZivThaller)
 
 Version: 1.2.5 (2015-01-31)
 -------------------------------------------------------------------------------
diff --git a/behave/formatter/sphinx_steps.py b/behave/formatter/sphinx_steps.py
index 3833b65..4cf555d 100644
--- a/behave/formatter/sphinx_steps.py
+++ b/behave/formatter/sphinx_steps.py
@@ -10,6 +10,9 @@ TODO:
 
 .. seealso::
     http://sphinx-doc.org/
+
+.. note:: REQUIRES docutils
+    :mod:`docutils` are needed to generate step-label for step references.
 """
 
 from __future__ import absolute_import, print_function
@@ -21,6 +24,16 @@ import inspect
 import os.path
 import sys
 
+try:
+    # -- SAFETY-NET:
+    import docutils
+    has_docutils = True
+
+    # -- NEEDED FOR: step-labels (and step-refs)
+    from docutils.nodes import fully_normalize_name
+except ImportError:
+    has_docutils = False
+
 
 # -----------------------------------------------------------------------------
 # HELPER CLASS:
@@ -102,6 +115,7 @@ class SphinxStepsDocumentGenerator(object):
     shows_step_module_info = True
     shows_step_module_overview = True
     make_step_index_entries = True
+    make_step_labels = has_docutils
 
     document_separator = "# -- DOCUMENT-END " + "-" * 60
     step_document_prefix = "step_module."
@@ -287,19 +301,20 @@ The following step definitions are provided here.
             index_id = self.make_step_definition_index_id(step_definition)
 
         heading = step_text
+        step_label = None
         if self.step_heading_prefix:
             heading = self.step_heading_prefix + step_text
-        self.document.write_heading(heading, level=2, index_id=index_id)
+        if has_docutils and self.make_step_labels:
+            # -- ADD STEP-LABEL (supports: step-refs by name)
+            # EXAMPLE: See also :ref:`When my step does "{something}"`.
+            step_label = fully_normalize_name(step_text)
+            # SKIP-HERE: self.document.write(".. _%s:\n\n" % step_label)
+        self.document.write_heading(heading, level=2, index_id=index_id, 
+                                    label=step_label)
         step_definition_doc = self.make_step_definition_doc(step_definition)
         self.document.write("%s\n" % step_definition_doc)
         self.document.write("\n")
 
-        # Add step label
-        from docutils.nodes import fully_normalize_name
-        step_text = fully_normalize_name(step_text)
-        step_lable = ".. _" + step_text + ":" + "\n"
-        self.document.write(step_lable)
-        self.document.write("\n")
 
 
 # -----------------------------------------------------------------------------
diff --git a/behave/formatter/sphinx_util.py b/behave/formatter/sphinx_util.py
index e1f7846..5e5cfbf 100644
--- a/behave/formatter/sphinx_util.py
+++ b/behave/formatter/sphinx_util.py
@@ -40,7 +40,7 @@ class DocumentWriter(object):
             self.stream.close()
         self.stream = None
 
-    def write_heading(self, heading, level=0, index_id=None):
+    def write_heading(self, heading, level=0, index_id=None, label=None):
         assert self.stream
         assert heading, "Heading should not be empty"
         assert 0 <= level < len(self.heading_styles)
@@ -55,6 +55,8 @@ class DocumentWriter(object):
             if isinstance(index_id, (list, tuple)):
                 index_id = ", ".join(index_id)
             self.stream.write(".. index:: %s\n\n" % index_id)
+        if label:
+            self.stream.write(".. _%s:\n\n" % label)
         if level == 0:
             self.stream.write("%s\n" % separator)
         self.stream.write("%s\n" % heading)
-- 
2.11.0