docs(bdd): Add BDD scenarios to documentation¶
Description¶
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.
Info¶
- Hash
f5cfe92b893776ba217bef708951d86cdeebb686
- Date
2020-09-27 22:43:49 +0200
- Parents
Merge branch ‘feature/twidi/entities-fields-validation’ into develop [decf9c35] — 2020-09-27 10:14:37 +0200
- Children
refactor(namespace): Remove the intermediary `_Namespace` model [27e4ea0a] — 2020-09-28 18:05:22 +0200
- Branches
- Tags
(No tags)
Changes¶
.gitignore¶
- Type
Modified
- Stats
+3 -1
@@ -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¶
- Type
Modified
- Stats
+1 -1
@@ -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¶
- Type
Modified
- Stats
+5 -4
@@ -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¶
- Type
Added
- Stats
+11 -0
@@ -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¶
- Type
Modified
- Stats
+24 -2
@@ -97,7 +97,7 @@ add_module_names = False
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¶
- Type
Modified
- Stats
+1 -0
@@ -6,4 +6,5 @@ Welcome to IssHub's documentation!
:maxdepth: 2
About <about>
+ Specifications <bdd/index>
Internals <internals>
docs/internals.rst¶
- Type
Modified
- Stats
+1 -1
@@ -6,4 +6,4 @@ IssHub internals
:maxdepth: 2
Git repository <git/index>
- Packages <source/modules>
+ Python packages <source/modules>