Merge branch 'feature/twidi/enhance-source-doc' into develop

.circleci/config.yml

@@ -152,7 +152,7 @@ jobs:
           name: Build documentation
           command: |
             source ~/venv/bin/activate
-            make doc-strict
+            GIT_TO_SPHINX_UPDATE_BRANCHES=TRUE make doc-strict
 
   # run check and tests for every commit in the history for which it is not already done
   check_every_commit:

docs/_static/css/custom.css

@@ -1,3 +1,68 @@
+/* Hide "View page source" link (because it links to source used for search) */
+.wy-breadcrumbs-aside {
+	display: none !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.
+ */
+dl.class > dd > dl.field-list ~ dl.attribute {
+	display: None;
+}
+/* Package owning the current package/module and link to git history, placed at the top right of the current package/module */
+.package-side-info {
+	float: right;
+	text-align: right;
+}
+.package-side-info a:nth-child(2) { /* link "view git history", on its own line and smaller */
+	display: block;
+	font-size: smaller;
+	margin-top: 3px;
+}
+/* Hide the real title and instead show our own with more text in it (to avoid polluting toctree with more text) */
+.package-or-module-title {
+	margin-top: 0;
+	font-weight: 700;
+	font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
+	font-size: 175%;
+}
+.package-side-info ~ .section h1 {
+	display: none;
+}
+/* List of sub-packages/modules of the current package:
+	- Make the title "Subpackages"/"Submodules" not bold, and placed just before the list
+	- Add a left border to the list to make it visually match with the title
+ */
+p.rubric.package-sub {
+	margin-bottom: 0;
+	font-weight: normal;
+}
+p.rubric.package-sub + .toctree-wrapper {
+	border-left: solid #404040 1px;
+	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 */
+.package-or-module-title ~ span.target:first-of-type + p {  /* module */
+	font-weight: 600;
+	font-style: italic;
+	font-size: larger;
+}
+/* Add emphasis to the first line of docstring of classes, methods and functions */
+dl.class > dd:first-of-type > p:nth-child(2),
+dl.method > dd:first-of-type > p:first-of-type,
+dl.function > dd:first-of-type > p:first-of-type {
+	font-weight: 600;
+	font-style: italic;
+}
+
+/* Handle more levels of entries in the left sidebar */
 .wy-menu-vertical li.toctree-l3.current li.toctree-l4>ul,
 .wy-menu-vertical li.toctree-l4.current li.toctree-l5>ul,
 .wy-menu-vertical li.toctree-l5.current li.toctree-l6>ul,
@@ -24,7 +89,7 @@
 	display: block
 }
 .wy-menu-vertical li.toctree-l4.current li[class*="toctree-l"]>a{
-    padding: .4045em 5.663em;
+	padding: .4045em 5.663em;
 }
 .wy-menu-vertical li.toctree-l5>a{
 	padding-left: 6.663em !important;
@@ -53,11 +118,3 @@
 .wy-menu-vertical li.toctree-l13>a{
 	padding-left: 14.663em !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.
- */
-dl.class > dd > dl.field-list ~ dl.attribute {
-	display: None;
-}

docs/apidoc_templates/module.rst_t

@@ -0,0 +1,16 @@
+.. rst-class:: package-side-info
+
+   in :doc:`{{ basename.split('.')[:-1] | join(".") }} <{{ basename.split('.')[:-1] | join(".") }}>`
+   :doc:`View Git history </git/content/{{ basename.split('.') | join("/") }}.py>`
+
+{{ basename.split('.')[-1] | e | heading }}
+
+.. rst-class:: package-or-module-title
+
+   {{ ['"', basename.split('.')[-1] | e, '" module'] | join("") }}
+
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+

docs/apidoc_templates/package.rst_t

@@ -0,0 +1,42 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames, section_name) -%}
+.. rubric:: {{ section_name }}
+   :class: package-sub
+
+.. toctree::
+{% for docname in docnames %}
+   {{ docname.split('.')[-1] }} <{{ docname }}>
+{%- endfor %}
+{%- endmacro %}
+
+.. rst-class:: package-side-info
+
+   {% if '.' in pkgname %}in :doc:`{{ pkgname.split('.')[:-1] | join(".") }} <{{ pkgname.split('.')[:-1] | join(".") }}>`{% else %}(root){% endif %}
+   :doc:`View Git history </git/content/{{ pkgname.split('.') | join("/") }}/__init__.py>`
+
+.. rst-class:: package-or-module-title
+
+   {{ ['"', pkgname.split('.')[-1] | e, '" package'] | join("") }}
+
+{{ pkgname.split('.')[-1] | e | heading }}
+
+
+{%- if subpackages %}
+{{ toctree(subpackages, "Subpackages") }}
+{% endif %}
+
+{%- if submodules %}
+{{ toctree(submodules, "Submodules") }}
+{% endif %}
+
+{%- if not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+

docs/conf.py

@@ -55,7 +55,7 @@
 # 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,44 +93,66 @@
 # -- 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(
         [
             "--force",
             "--module-first",
             "--separate",
+            "-d",  # maxdepth
+            "6",
+            "--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 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_git_to_sphinx)
     # 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, "..")),
-        ]
-    )