conf.py¶
Last source¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | # Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import subprocess
import sys
from glob import glob
from sphinx.ext import apidoc
# for apidoc
sys.path.insert(0, os.path.abspath("../isshub"))
# default env var to be used by the doc builder, for example readthedocs
# os.environ.setdefault("XXX", "yyy")
# -- Project information -----------------------------------------------------
project = "IssHub"
copyright = '2019, Stéphane "Twidi" Angel'
author = 'Stéphane "Twidi" Angel'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.doctest",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
"sphinx.ext.graphviz",
"sphinx_autodoc_typehints",
"sphinxprettysearchresults",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "apidoc_templates"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_rtd_theme"
html_theme_options = {
"navigation_depth": -1,
"collapse_navigation": True,
"sticky_navigation": True,
"includehidden": True,
"titles_only": False,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = "isshubdoc"
# -- Extension configuration -------------------------------------------------
html_use_old_search_snippets = True
# -- Run apidoc when building the documentation-------------------------------
napoleon_use_ivar = True
autodoc_member_order = "bysource"
add_module_names = False
def run_apidoc(_):
"""Run apidoc on the project and store source doc in ``source`` dir."""
current_dir = os.path.dirname(__file__)
output_path = os.path.join(current_dir, "source")
source_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
exclude_paths = [
os.path.join(source_path, exclude_path) for exclude_path in ["*/tests/*"]
]
apidoc.main(
[
"--force",
"--module-first",
"--separate",
"-d", # maxdepth
"6",
"--doc-project",
"Python packages",
"--templatedir",
os.path.join(current_dir, "apidoc_templates"),
"--output-dir",
output_path,
source_path,
]
+ exclude_paths
)
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",
"4", # avoid scenarios for ``isshub.domain.contexts`` (may to too much/not enough later)
]
)
# add the diagrams
subprocess.run(
[
os.path.join(current_dir, "domain_contexts_diagrams.py"),
output_path,
]
)
# incorporate the diagrams in each contexts doc
for file in glob(os.path.join(output_path, "*-entities.dot")):
base_name = os.path.basename(file)[:-13]
rst_file = os.path.join(output_path, f"{base_name}-toc.rst")
with open(rst_file, "r") as file_d:
rst_lines = file_d.readlines()
rst_lines.insert(
3,
"Diagrams\n--------\n\n"
"Entities\n~~~~~~~~\n\n"
f".. graphviz:: {base_name}-entities.dot\n\n"
"Repositories\n~~~~~~~~~~~~\n\n"
f".. graphviz:: {base_name}-repositories.dot\n\n"
"BDD features\n------------\n\n",
)
with open(rst_file, "w") as file_d:
file_d.write("".join(rst_lines))
def run_git_to_sphinx(_):
"""Add git content into doc"""
update_remote_branches_env_var = "GIT_TO_SPHINX_UPDATE_BRANCHES"
update_remote_branches = os.environ.get(update_remote_branches_env_var)
if os.environ.get("READTHEDOCS"):
os.environ[update_remote_branches_env_var] = "TRUE"
try:
current_dir = os.path.dirname(__file__)
subprocess.run(
[
os.path.join(current_dir, "git_to_sphinx.py"),
os.path.normpath(os.path.join(current_dir, "..")),
os.path.normpath(os.path.join(current_dir, "source")),
]
)
finally:
if not update_remote_branches and os.environ.get(
update_remote_branches_env_var
):
del os.environ[update_remote_branches_env_var]
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")
|
Changes¶
docs(domain): Add diagrams for repositories¶
- Commit
- Hash
- Date
2020-10-07 12:10:48 +0200
- Type
Modified
- Stats
+9 -1
@@ -159,7 +159,15 @@ def run_gherkindoc(_):
rst_file = os.path.join(output_path, f"{base_name}-toc.rst")
with open(rst_file, "r") as file_d:
rst_lines = file_d.readlines()
- rst_lines.insert(3, f".. graphviz:: {base_name}-entities.dot\n\n")
+ rst_lines.insert(
+ 3,
+ "Diagrams\n--------\n\n"
+ "Entities\n~~~~~~~~\n\n"
+ f".. graphviz:: {base_name}-entities.dot\n\n"
+ "Repositories\n~~~~~~~~~~~~\n\n"
+ f".. graphviz:: {base_name}-repositories.dot\n\n"
+ "BDD features\n------------\n\n",
+ )
with open(rst_file, "w") as file_d:
file_d.write("".join(rst_lines))
feat(repository): Add domain repositories¶
- Commit
- Hash
- Date
2020-10-06 17:30:45 +0200
- Type
Modified
- Stats
+2 -1
@@ -93,6 +93,7 @@ html_use_old_search_snippets = True
# -- Run apidoc when building the documentation-------------------------------
napoleon_use_ivar = True
+autodoc_member_order = "bysource"
add_module_names = False
@@ -140,7 +141,7 @@ def run_gherkindoc(_):
"--toc-name",
"index",
"--maxtocdepth",
- "5",
+ "4", # avoid scenarios for ``isshub.domain.contexts`` (may to too much/not enough later)
]
)
docs(domain): Add diagram of entities for each domain context¶
- Commit
- Hash
- Date
2020-10-04 11:50:37 +0200
- Type
Modified
- Stats
+20 -2
@@ -12,11 +12,10 @@
#
-import glob
-import importlib
import os
import subprocess
import sys
+from glob import glob
from sphinx.ext import apidoc
@@ -45,6 +44,7 @@ extensions = [
"sphinx.ext.doctest",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
+ "sphinx.ext.graphviz",
"sphinx_autodoc_typehints",
"sphinxprettysearchresults",
]
@@ -144,6 +144,24 @@ def run_gherkindoc(_):
]
)
+ # add the diagrams
+ subprocess.run(
+ [
+ os.path.join(current_dir, "domain_contexts_diagrams.py"),
+ output_path,
+ ]
+ )
+
+ # incorporate the diagrams in each contexts doc
+ for file in glob(os.path.join(output_path, "*-entities.dot")):
+ base_name = os.path.basename(file)[:-13]
+ rst_file = os.path.join(output_path, f"{base_name}-toc.rst")
+ with open(rst_file, "r") as file_d:
+ rst_lines = file_d.readlines()
+ rst_lines.insert(3, f".. graphviz:: {base_name}-entities.dot\n\n")
+ with open(rst_file, "w") as file_d:
+ file_d.write("".join(rst_lines))
+
def run_git_to_sphinx(_):
"""Add git content into doc"""
docs(bdd): Add BDD scenarios to documentation¶
- Commit
- Hash
- Date
2020-09-27 22:43:49 +0200
- 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(source): Reduce white space in toc tree¶
- Commit
- Hash
- Date
2020-09-26 12:29:40 +0200
- Type
Modified
- Stats
+2 -0
@@ -111,6 +111,8 @@ def run_apidoc(_):
"--force",
"--module-first",
"--separate",
+ "-d", # maxdepth
+ "6",
"--doc-project",
"Packages",
"--templatedir",
docs(source): Make links between python files in source and git¶
- Commit
- Hash
- Date
2020-09-25 23:40:13 +0200
- Type
Modified
- Stats
+2 -2
@@ -123,7 +123,7 @@ def run_apidoc(_):
)
-def run_git_to_sphinx():
+def run_git_to_sphinx(_):
"""Add git content into doc"""
update_remote_branches_env_var = "GIT_TO_SPHINX_UPDATE_BRANCHES"
@@ -150,7 +150,7 @@ def run_git_to_sphinx():
def setup(app):
# Run apidoc
app.connect("builder-inited", run_apidoc)
+ app.connect("builder-inited", run_git_to_sphinx)
# Add custom css/js for rtd template
app.add_css_file("css/custom.css")
app.add_js_file("js/custom.js")
- run_git_to_sphinx()
docs(git): Only update remote branches if asked¶
- Commit
- Hash
- Date
2020-09-25 23:37:37 +0200
- Type
Modified
- Stats
+25 -8
@@ -123,17 +123,34 @@ def run_apidoc(_):
)
+def run_git_to_sphinx():
+ """Add git content into doc"""
+
+ update_remote_branches_env_var = "GIT_TO_SPHINX_UPDATE_BRANCHES"
+ update_remote_branches = os.environ.get(update_remote_branches_env_var)
+ if os.environ.get("READTHEDOCS"):
+ os.environ[update_remote_branches_env_var] = "TRUE"
+
+ try:
+ current_dir = os.path.dirname(__file__)
+ subprocess.run(
+ [
+ os.path.join(current_dir, "git_to_sphinx.py"),
+ os.path.normpath(os.path.join(current_dir, "..")),
+ os.path.normpath(os.path.join(current_dir, "source")),
+ ]
+ )
+ finally:
+ if not update_remote_branches and os.environ.get(
+ update_remote_branches_env_var
+ ):
+ del os.environ[update_remote_branches_env_var]
+
+
def setup(app):
# Run apidoc
app.connect("builder-inited", run_apidoc)
# Add custom css/js for rtd template
app.add_css_file("css/custom.css")
app.add_js_file("js/custom.js")
- # Add git content into doc
- current_dir = os.path.dirname(__file__)
- subprocess.run(
- [
- os.path.join(current_dir, "git_to_sphinx.py"),
- os.path.normpath(os.path.join(current_dir, "..")),
- ]
- )
+ run_git_to_sphinx()
docs(source): Lighten source code pages¶
- Commit
- Hash
- Date
2020-09-25 23:36:45 +0200
- Type
Modified
- Stats
+10 -9
@@ -55,7 +55,7 @@ templates_path = ["_templates"]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "apidoc_templates"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
@@ -93,15 +93,18 @@ html_use_old_search_snippets = True
# -- Run apidoc when building the documentation-------------------------------
napoleon_use_ivar = True
+add_module_names = False
def run_apidoc(_):
"""Run apidoc on the marsha project and store source doc in ``source`` dir."""
+
current_dir = os.path.dirname(__file__)
- source_path = os.path.join(current_dir, "source")
- output_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
+
+ output_path = os.path.join(current_dir, "source")
+ source_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
exclude_paths = [
- os.path.join(output_path, exclude_path) for exclude_path in ["*/tests/*"]
+ os.path.join(source_path, exclude_path) for exclude_path in ["*/tests/*"]
]
apidoc.main(
[
@@ -110,16 +113,14 @@ def run_apidoc(_):
"--separate",
"--doc-project",
"Packages",
+ "--templatedir",
+ os.path.join(current_dir, "apidoc_templates"),
"--output-dir",
- source_path,
output_path,
+ source_path,
]
+ exclude_paths
)
- subprocess.run(
- ["sed", "-i", "-e", r"s/ \(module\|package\)$//"]
- + glob.glob(os.path.join(source_path, "*.rst"))
- )
def setup(app):
docs(source): Rename source index page to Packages¶
- Commit
- Hash
- Date
2020-09-25 23:36:22 +0200
- Type
Modified
- Stats
+2 -0
@@ -108,6 +108,8 @@ def run_apidoc(_):
"--force",
"--module-first",
"--separate",
+ "--doc-project",
+ "Packages",
"--output-dir",
source_path,
output_path,
chore: Fix breaking changes from updated dependencies¶
- Commit
- Hash
- Date
2020-09-25 22:54:00 +0200
- Type
Modified
- Stats
+2 -0
@@ -92,6 +92,8 @@ html_use_old_search_snippets = True
# -- Run apidoc when building the documentation-------------------------------
+napoleon_use_ivar = True
+
def run_apidoc(_):
"""Run apidoc on the marsha project and store source doc in ``source`` dir."""
docs(git): Add git commits to documentation¶
- Commit
- Hash
- Date
2019-06-03 13:54:59 +0200
- Type
Modified
- Stats
+11 -0
@@ -121,3 +121,14 @@ def run_apidoc(_):
def setup(app):
# Run apidoc
app.connect("builder-inited", run_apidoc)
+ # Add custom css/js for rtd template
+ app.add_css_file("css/custom.css")
+ app.add_js_file("js/custom.js")
+ # Add git content into doc
+ current_dir = os.path.dirname(__file__)
+ subprocess.run(
+ [
+ os.path.join(current_dir, "git_to_sphinx.py"),
+ os.path.normpath(os.path.join(current_dir, "..")),
+ ]
+ )
docs: Documentation generation¶
- Commit
- Hash
- Date
2019-05-27 17:14:11 +0200
- Type
Added
- Stats
+123 -0
@@ -0,0 +1,123 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+
+import glob
+import importlib
+import os
+import subprocess
+import sys
+
+from sphinx.ext import apidoc
+
+
+# for apidoc
+sys.path.insert(0, os.path.abspath("../isshub"))
+
+# default env var to be used by the doc builder, for example readthedocs
+# os.environ.setdefault("XXX", "yyy")
+
+
+# -- Project information -----------------------------------------------------
+
+project = "IssHub"
+copyright = '2019, Stéphane "Twidi" Angel'
+author = 'Stéphane "Twidi" Angel'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ "sphinx.ext.autodoc",
+ "sphinx.ext.doctest",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.napoleon",
+ "sphinx_autodoc_typehints",
+ "sphinxprettysearchresults",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+html_theme_options = {
+ "navigation_depth": -1,
+ "collapse_navigation": True,
+ "sticky_navigation": True,
+ "includehidden": True,
+ "titles_only": False,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "isshubdoc"
+
+# -- Extension configuration -------------------------------------------------
+
+html_use_old_search_snippets = True
+
+# -- Run apidoc when building the documentation-------------------------------
+
+
+def run_apidoc(_):
+ """Run apidoc on the marsha project and store source doc in ``source`` dir."""
+ current_dir = os.path.dirname(__file__)
+ source_path = os.path.join(current_dir, "source")
+ output_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
+ exclude_paths = [
+ os.path.join(output_path, exclude_path) for exclude_path in ["*/tests/*"]
+ ]
+ apidoc.main(
+ [
+ "--force",
+ "--module-first",
+ "--separate",
+ "--output-dir",
+ source_path,
+ output_path,
+ ]
+ + exclude_paths
+ )
+ subprocess.run(
+ ["sed", "-i", "-e", r"s/ \(module\|package\)$//"]
+ + glob.glob(os.path.join(source_path, "*.rst"))
+ )
+
+
+def setup(app):
+ # Run apidoc
+ app.connect("builder-inited", run_apidoc)