docs(source): Lighten source code pages¶
Description¶
Abstract¶
Use our own templates for apidoc.
Motivation¶
Two main reasons: - “Subpackages” and “Submodules” where present everywhere, in toctree and pages - packages/modules always and fully qualified names and as they can be long, where to heavy for the pages
Rationale¶
We copied the apidoc templates from site-packages/sphinx/templates/apidoc/ to docs/apidoc_templates/ and heavily updated their content, also playing with CSS where we cannot change the rendering (the templates are RST and we don’t control how they are rendered to html), so thanks to the rst-class directive we could play.
In particular: - remove “Subpackages” and “Submodules” from toctrees - add them back as a simple <p> in the pages - use only the non-qualified package name in the title of the page (lighter toctree in the sidebar and in breadcrumb) - hide this title and display a little more complete - and display the “owner package” on the right of the title
Info¶
- Hash
a94891ffd23551785a40128d395b4014dac19472
- Date
2020-09-25 23:36:45 +0200
- Parents
docs(source): Rename source index page to `Packages` [6646f12f] — 2020-09-25 23:36:22 +0200
- Children
docs: Hide “View page source” links [158f5927] — 2020-09-25 23:37:12 +0200
- Branches
- Tags
(No tags)
Changes¶
docs/_static/css/custom.css¶
- Type
Modified
- Stats
+27 -0
@@ -5,6 +5,33 @@ Side effect: If attributes are not defined in docstrings, they won't appear at a
dl.class > dd > dl.field-list ~ dl.attribute {
display: None;
}
+/* Package owning the current package/module, placed at the top right of the current package/module */
+.package-owner {
+ float: right;
+}
+/* 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-owner ~ .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;
+}
/* Handle more levels of entries in the left sidebar */
.wy-menu-vertical li.toctree-l3.current li.toctree-l4>ul,
docs/apidoc_templates/module.rst_t¶
- Type
Added
- Stats
+15 -0
@@ -0,0 +1,15 @@
+.. rst-class:: package-owner
+
+ in :doc:`{{ basename.split('.')[:-1] | join(".") }} <{{ basename.split('.')[:-1] | join(".") }}>`
+
+{{ 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¶
- Type
Added
- Stats
+43 -0
@@ -0,0 +1,43 @@
+{%- 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-owner
+
+ {% if '.' in pkgname %}in :doc:`{{ pkgname.split('.')[:-1] | join(".") }} <{{ pkgname.split('.')[:-1] | join(".") }}>`{% else %}(root){% endif %}
+
+
+.. 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¶
- 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):