docs(source): Make links between python files in source and git¶
Description¶
Abstract
========
- In the files page of the "git" part of the documentation, if they are
still existing python files, add a link to the "source" part of the
documentation.
- In the "source" part of the documentation, add a link to the "git"
part of the documentation, pointing to the file page, with git history.
Motivation
==========
Both view made possible to view the actual code source. But without
links between them, it was not really an option to have:
- in the "git" view, an abstract of the content of a python
package/module
- in the "source" view, an idea of how the file evolved
Rationale
=========
N/A
Info¶
- Hash
04393b775843bcf46b9910b7533681d9965252af
- Date
2020-09-25 23:40:13 +0200
- Parents
docs(git): Only update remote branches if asked [207325fe] — 2020-09-25 23:37:37 +0200
- Children
docs(examples): Add examples in functions docstring [74b050b5] — 2020-09-26 12:03:01 +0200
- Branches
- Tags
(No tags)
Changes¶
docs/_static/css/custom.css¶
- Type
Modified
- Stats
+9 -3
@@ -9,9 +9,15 @@ 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 {
+/* 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 {
@@ -20,7 +26,7 @@ dl.class > dd > dl.field-list ~ dl.attribute {
font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
font-size: 175%;
}
-.package-owner ~ .section h1 {
+.package-side-info ~ .section h1 {
display: none;
}
/* List of sub-packages/modules of the current package:
docs/apidoc_templates/module.rst_t¶
- Type
Modified
- Stats
+2 -1
@@ -1,6 +1,7 @@
-.. rst-class:: package-owner
+.. 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 }}
docs/apidoc_templates/package.rst_t¶
- Type
Modified
- Stats
+2 -3
@@ -15,11 +15,10 @@
{%- endfor %}
{%- endmacro %}
-
-.. rst-class:: package-owner
+.. 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
docs/conf.py¶
- 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_to_sphinx.py¶
- Type
Modified
- Stats
+21 -2
@@ -22,7 +22,10 @@ from pydriller.git_repository import GitRepository as GitRepositoryBase
DOC_DIRNAME = "git"
-BASEPATH = os.path.join(os.path.dirname(__file__), DOC_DIRNAME)
+SOURCE_DIRNAME = "source"
+DIRNAME = os.path.dirname(__file__)
+BASEPATH = os.path.join(DIRNAME, DOC_DIRNAME)
+SOURCE_BASE_PATH = os.path.join(DIRNAME, SOURCE_DIRNAME)
REMOVED = " (removed)"
@@ -349,6 +352,10 @@ Changes
"""
+LINK_TO_SOURCE_TEMPLATE = """\
+:doc:`View documentation </{source_dirname}/{python_path}>`
+"""
+
FILE_PAGE_TEMPLATE = """\
{title_line}
{title}
@@ -374,7 +381,7 @@ Last update
-----------
Last source
-----------
-
+{documentation}
{source_code}
-------
@@ -763,6 +770,17 @@ def render_file_pages(path, changes_by_file, current_tree):
source_code = last_change[1].source_code or find_last_source_code(
path, last_change, changes_by_file
)
+ documentation = ""
+ if path.endswith(".py"):
+ parts = path[:-3].split("/")
+ if parts[-1] == "__init__":
+ parts.pop()
+ python_path = ".".join(parts)
+ if os.path.exists(os.path.join(SOURCE_BASE_PATH, python_path + ".rst")):
+ documentation = LINK_TO_SOURCE_TEMPLATE.format(
+ python_path=python_path, source_dirname=SOURCE_DIRNAME
+ )
+
return {
f"content/{escape_path(path)}.rst": FILE_PAGE_TEMPLATE.format(
path=path,
@@ -788,6 +806,7 @@ def render_file_pages(path, changes_by_file, current_tree):
new_path=render_new_path(last_modification.new_path, DOC_DIRNAME)
if last_modification.new_path and last_modification.new_path != path
else "",
+ documentation=documentation,
parent_old="" if path_in_tree(dirname, current_tree) else REMOVED,
)
}