docs(bdd): Add BDD scenarios to documentation

Abstract
========

Add a new "Specifications" entries at the root of the documentation,
containing all features and scenarios.

Motivation
==========

We use BDD as specification, so it's important to have the features and
scenarios in the documentation.

Rationale
=========

We use the `sphinx-gherkindoc` package to do the heavy work of finding
the `.feature` files and rendering the documentation.

.gitignore

@@ -74,7 +74,9 @@ instance/
 docs/_build/
 # Doc from code
 docs/source/
-# Got 2 RST
+# Doc from bdd features
+docs/bdd/
+# Git 2 RST
 docs/git/
 
 # PyBuilder

Makefile

@@ -61,7 +61,7 @@ clean-doc / clean-docs:  ## Clean the documentation directories
 clean-docs: clean-doc  # we allow "clean-doc" and "clean-docs"
 clean-doc:
 	@echo "$(BOLD)Cleaning documentation directories$(RESET)"
-	@rm -rf docs/source docs/git
+	@rm -rf docs/source docs/git docs/bdd
 	@cd docs && $(MAKE) clean
 
 .PHONY: tests test

docs/_static/css/custom.css

@@ -2,6 +2,11 @@
 .wy-breadcrumbs-aside {
 	display: none !important;
 }
+/* Reduce vertical white space in toc trees */
+.toctree-wrapper ul ul {
+    margin-top: 0 !important;
+    margin-bottom: 0 !important;
+}
 /* Hide class attributes because they are duplicate of the class vars found by napoleon plugins
 and those vars are more detailed.
 Side effect: If attributes are not defined in docstrings, they won't appear at all.
@@ -42,10 +47,6 @@ p.rubric.package-sub + .toctree-wrapper {
 	margin-left: 6px;
 	padding-top: 6px;
 }
-div#packages > h1 + .toctree-wrapper ul ul, p.package-sub  + .toctree-wrapper ul ul {
-    margin-top: 0;
-    margin-bottom: 0;
-}
 /* Add emphasis to the first line of docstring of packages and modules */
 .package-or-module-title + .section > span.target:first-of-type + p,  /* package with no content */
 .package-or-module-title + .section > span + h1:first-of-type + p, /* package with content */

docs/_static/css/gherkin.css

@@ -0,0 +1,11 @@
+/* Style for doc generated by `sphinx-gherkindoc` */
+div[id^="scenario-"] h2 ~ * {
+  margin-left: 2em !important;
+}
+.gherkin-scenario-content {
+    font-weight: normal;
+}
+.gherkin-step-keyword {
+    font-weight: bold;
+}
+

docs/conf.py

@@ -97,7 +97,7 @@
 
 
 def run_apidoc(_):
-    """Run apidoc on the marsha project and store source doc in ``source`` dir."""
+    """Run apidoc on the project and store source doc in ``source`` dir."""
 
     current_dir = os.path.dirname(__file__)
 
@@ -114,7 +114,7 @@ def run_apidoc(_):
             "-d",  # maxdepth
             "6",
             "--doc-project",
-            "Packages",
+            "Python packages",
             "--templatedir",
             os.path.join(current_dir, "apidoc_templates"),
             "--output-dir",
@@ -125,6 +125,26 @@ def run_apidoc(_):
     )
 
 
+def run_gherkindoc(_):
+    """Run gherkindoc on the project and store bdd doc in ``bdd`` dir."""
+
+    current_dir = os.path.dirname(__file__)
+
+    output_path = os.path.join(current_dir, "bdd")
+    source_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
+    subprocess.run(
+        [
+            "sphinx-gherkindoc",
+            source_path,
+            output_path,
+            "--toc-name",
+            "index",
+            "--maxtocdepth",
+            "5",
+        ]
+    )
+
+
 def run_git_to_sphinx(_):
     """Add git content into doc"""
 
@@ -152,7 +172,9 @@ def run_git_to_sphinx(_):
 def setup(app):
     # Run apidoc
     app.connect("builder-inited", run_apidoc)
+    app.connect("builder-inited", run_gherkindoc)
     app.connect("builder-inited", run_git_to_sphinx)
     # Add custom css/js for rtd template
     app.add_css_file("css/custom.css")
+    app.add_css_file("css/gherkin.css")
     app.add_js_file("js/custom.js")

docs/index.rst

@@ -6,4 +6,5 @@ Welcome to IssHub's documentation!
   :maxdepth: 2
 
    About <about>
+   Specifications <bdd/index>
    Internals <internals>

docs/internals.rst

@@ -6,4 +6,4 @@ IssHub internals
   :maxdepth: 2
 
    Git repository <git/index>
-   Packages <source/modules>
+   Python packages <source/modules>

setup.cfg

@@ -65,6 +65,7 @@ docs =
     rstcheck
     sphinx
     sphinx-autodoc-typehints
+    sphinx-gherkindoc
     sphinx_rtd_theme
     sphinxprettysearchresults