From 05708aaf35967ec5cd2f65dd59c4644f994f3d31 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 12:01:57 -0400 Subject: [PATCH 01/27] Support for online source links Refs https://github.com/pdoc3/pdoc/issues/100 --- pdoc/html_helpers.py | 32 +++++++++++++++++++++++++++++++- pdoc/templates/config.mako | 7 +++++++ pdoc/templates/html.mako | 9 +++++++-- 3 files changed, 45 insertions(+), 3 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index b5ad9812..8351a980 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -2,8 +2,9 @@ Helper functions for HTML output. """ import inspect -import os.path +import os import re +import subprocess from functools import partial, lru_cache from typing import Callable, Match from warnings import warn @@ -430,3 +431,32 @@ def extract_toc(text: str): if toc.endswith('

'): # CUT was put into its own paragraph toc = toc[:-3].rstrip() return toc + + +@lru_cache() +def _get_head_commit(): + """ + If the working directory is part of a git repository, return the + head git commit hash. Otherwise, raise a CalledProcessError. + """ + process_args = ['git', 'rev-parse', 'HEAD'] + commit = subprocess.check_output(process_args, universal_newlines=True) + return commit.strip() + + +def get_online_source_link(template: str, dobj: pdoc.Doc): + """ + Interpolate `template` as a formatted string literal using values extracted + from `dobj` and the working directory. + """ + try: + lines, start_line = inspect.getsourcelines(dobj.obj) + end_line = start_line + len(lines) + abs_path = inspect.getmodule(dobj.obj).__file__ + file_path = os.path.relpath(abs_path, os.getcwd()) # project-relative path + commit = _get_head_commit() + url = template.format(**locals()) + return url + except Exception: + # TODO what sort of error handling do we want: logging / warnings? + return None diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 48c0b61a..970def7c 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -12,6 +12,13 @@ # Disabling this can improve rendering speed of large modules. show_source_code = True + # If uncommented, provide links to source code online. + # online_source_link is a string whose str.format method is + # called to template it for a given documentation object. + # Supported keywords for interpolation are commit, path, start_line, and end_line. + # online_source_link = 'https://github.com/ORG/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + online_source_link = 'https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line} + # A prefix to use for every HTML hyperlink in the generated documentation. # No prefix results in all links being relative. link_prefix = '' diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index ef0ce266..b8747301 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -2,7 +2,7 @@ import os import pdoc - from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html + from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_online_source_link def link(d, name=None, fmt='{}'): @@ -22,8 +22,13 @@ <%def name="show_source(d)"> % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None): +

+ + Online source code + +
- Source code + Expand source code 
${d.source | h}
%endif From 5e9cfbed405aecf7c7df2c87a7f5b4cb96643742 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 12:07:57 -0400 Subject: [PATCH 02/27] Activate online_source_link in doc/build.sh --- doc/build.sh | 1 + pdoc/templates/config.mako | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build.sh b/doc/build.sh index 70899edb..1773cd57 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -21,6 +21,7 @@ rm -r "$BUILDROOT" 2>/dev/null || true pushd "$DOCROOT/.." >/dev/null pdoc3 --html \ ${IS_RELEASE+--template-dir "$DOCROOT/pdoc_template"} \ + --config "online_source_link=https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}" \ --output-dir "$BUILDROOT" \ pdoc popd >/dev/null diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 970def7c..26a4c028 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -17,7 +17,6 @@ # called to template it for a given documentation object. # Supported keywords for interpolation are commit, path, start_line, and end_line. # online_source_link = 'https://github.com/ORG/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' - online_source_link = 'https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line} # A prefix to use for every HTML hyperlink in the generated documentation. # No prefix results in all links being relative. From a46ecf34a62dbe42180c3222b66e078ac1ffbf1a Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 12:12:51 -0400 Subject: [PATCH 03/27] Separate online_source_link from show_source_code in html.mako --- pdoc/templates/html.mako | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index b8747301..fa99e0aa 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -21,12 +21,13 @@ <%def name="ident(name)">${name} <%def name="show_source(d)"> - % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None): + % if 'online_source_link' in locals() and online_source_link and d.source and d.obj is not getattr(d.inherits, 'obj', None):
- Online source code + Online source code
+ % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None):
Expand source code 
${d.source | h}
From 3b6af2ff9d5b03f20e2d1319ec70ebc2fbd00777 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 13:08:41 -0400 Subject: [PATCH 04/27] html.mako: terminate if statement --- pdoc/templates/html.mako | 1 + 1 file changed, 1 insertion(+) diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index fa99e0aa..1853d8d3 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -27,6 +27,7 @@ Online source code + %endif % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None):
Expand source code From 8dbd53d0d545a047cd7c0ad47e14a632941d7723 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 13:13:28 -0400 Subject: [PATCH 05/27] Quote online_source_link --config https://travis-ci.org/pdoc3/pdoc/jobs/578458065#L231 --- doc/build.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build.sh b/doc/build.sh index 1773cd57..b08efe8f 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -21,7 +21,7 @@ rm -r "$BUILDROOT" 2>/dev/null || true pushd "$DOCROOT/.." >/dev/null pdoc3 --html \ ${IS_RELEASE+--template-dir "$DOCROOT/pdoc_template"} \ - --config "online_source_link=https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}" \ + --config "online_source_link='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \ --output-dir "$BUILDROOT" \ pdoc popd >/dev/null From d8fec0ae10fd4343e9d5ddc49111e3ef067cb714 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 13:20:42 -0400 Subject: [PATCH 06/27] Set online_source_link as none in config.mako UserWarning: Unknown configuration variables (not in config.mako) https://travis-ci.org/pdoc3/pdoc/jobs/578459994#L220 --- pdoc/templates/config.mako | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 26a4c028..469fdcb9 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -12,11 +12,12 @@ # Disabling this can improve rendering speed of large modules. show_source_code = True - # If uncommented, provide links to source code online. + # Provide links to source code online. # online_source_link is a string whose str.format method is # called to template it for a given documentation object. # Supported keywords for interpolation are commit, path, start_line, and end_line. # online_source_link = 'https://github.com/ORG/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + online_source_link = None # A prefix to use for every HTML hyperlink in the generated documentation. # No prefix results in all links being relative. From b998fb20548eb8b37c4a0aa07c7371eb43cc3166 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 13:39:21 -0400 Subject: [PATCH 07/27] Log exception for debugging https://travis-ci.org/pdoc3/pdoc/jobs/578462696#L223 --- pdoc/html_helpers.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 8351a980..6f462840 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -459,4 +459,6 @@ def get_online_source_link(template: str, dobj: pdoc.Doc): return url except Exception: # TODO what sort of error handling do we want: logging / warnings? + import logging + logging.exception('get_online_source_link for {} failed'.format(dobj)) return None From af15129150482b702029f4d561bf1a2809e6a33c Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 13:48:59 -0400 Subject: [PATCH 08/27] file_path to path --- pdoc/html_helpers.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 6f462840..90d270ae 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -453,12 +453,12 @@ def get_online_source_link(template: str, dobj: pdoc.Doc): lines, start_line = inspect.getsourcelines(dobj.obj) end_line = start_line + len(lines) abs_path = inspect.getmodule(dobj.obj).__file__ - file_path = os.path.relpath(abs_path, os.getcwd()) # project-relative path + path = os.path.relpath(abs_path, os.getcwd()) # project-relative path commit = _get_head_commit() url = template.format(**locals()) return url except Exception: # TODO what sort of error handling do we want: logging / warnings? import logging - logging.exception('get_online_source_link for {} failed'.format(dobj)) + logging.exception('get_online_source_link for {} failed.'.format(dobj)) return None From d51d2afda209e7a21d970f0c06a723ae13a9baec Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Thu, 29 Aug 2019 14:43:41 -0400 Subject: [PATCH 09/27] simplify html_helpers --- pdoc/html_helpers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 90d270ae..b3268ff1 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -452,7 +452,7 @@ def get_online_source_link(template: str, dobj: pdoc.Doc): try: lines, start_line = inspect.getsourcelines(dobj.obj) end_line = start_line + len(lines) - abs_path = inspect.getmodule(dobj.obj).__file__ + abs_path = inspect.getfile(dobj.obj) path = os.path.relpath(abs_path, os.getcwd()) # project-relative path commit = _get_head_commit() url = template.format(**locals()) From d11a0dbdc2ca5a157ba0d4c0aa11744fd08c9f6d Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Fri, 30 Aug 2019 11:31:29 -0400 Subject: [PATCH 10/27] Some review revisions. _get_head_commit warnings --- pdoc/html_helpers.py | 14 ++++++++++++-- pdoc/templates/config.mako | 2 +- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index b3268ff1..520faadb 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -440,8 +440,18 @@ def _get_head_commit(): head git commit hash. Otherwise, raise a CalledProcessError. """ process_args = ['git', 'rev-parse', 'HEAD'] - commit = subprocess.check_output(process_args, universal_newlines=True) - return commit.strip() + try: + commit = subprocess.check_output(process_args, universal_newlines=True) + return commit.strip() + except FileNotFoundError as error: + warn("git executable not found on system:\n{}".format(error)) + except subprocess.CalledProcessError as error: + warn( + "Ensure pdoc is run within a git repository.\n" + "`{}` failed with output:\n{}" + .format(' '.join(process_args), error.output) + ) + return None def get_online_source_link(template: str, dobj: pdoc.Doc): diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 469fdcb9..20fe1064 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -16,7 +16,7 @@ # online_source_link is a string whose str.format method is # called to template it for a given documentation object. # Supported keywords for interpolation are commit, path, start_line, and end_line. - # online_source_link = 'https://github.com/ORG/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + # online_source_link = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' online_source_link = None # A prefix to use for every HTML hyperlink in the generated documentation. From df061c1bdfc0ec73c54751695f530e7493a30868 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Fri, 30 Aug 2019 11:46:29 -0400 Subject: [PATCH 11/27] Use warnings not logging --- pdoc/html_helpers.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 520faadb..c89b0ece 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -5,6 +5,7 @@ import os import re import subprocess +import traceback from functools import partial, lru_cache from typing import Callable, Match from warnings import warn @@ -468,7 +469,5 @@ def get_online_source_link(template: str, dobj: pdoc.Doc): url = template.format(**locals()) return url except Exception: - # TODO what sort of error handling do we want: logging / warnings? - import logging - logging.exception('get_online_source_link for {} failed.'.format(dobj)) + warn('get_online_source_link for {} failed:\n{}'.format(dobj, traceback.format_exc())) return None From 850d3b742fd9b052a23d11b862ee01e8d4838580 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Tue, 3 Sep 2019 14:30:49 -0400 Subject: [PATCH 12/27] Easy revisions based on PR review --- doc/build.sh | 2 +- pdoc/html_helpers.py | 6 +++--- pdoc/templates/config.mako | 6 +++--- pdoc/templates/html.mako | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/build.sh b/doc/build.sh index b08efe8f..a514ff49 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -21,7 +21,7 @@ rm -r "$BUILDROOT" 2>/dev/null || true pushd "$DOCROOT/.." >/dev/null pdoc3 --html \ ${IS_RELEASE+--template-dir "$DOCROOT/pdoc_template"} \ - --config "online_source_link='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \ + --config "repo_link_template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \ --output-dir "$BUILDROOT" \ pdoc popd >/dev/null diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index c89b0ece..47ed08b4 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -444,7 +444,7 @@ def _get_head_commit(): try: commit = subprocess.check_output(process_args, universal_newlines=True) return commit.strip() - except FileNotFoundError as error: + except OSError as error: warn("git executable not found on system:\n{}".format(error)) except subprocess.CalledProcessError as error: warn( @@ -455,7 +455,7 @@ def _get_head_commit(): return None -def get_online_source_link(template: str, dobj: pdoc.Doc): +def get_repo_link_template(template: str, dobj: pdoc.Doc): """ Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working directory. @@ -469,5 +469,5 @@ def get_online_source_link(template: str, dobj: pdoc.Doc): url = template.format(**locals()) return url except Exception: - warn('get_online_source_link for {} failed:\n{}'.format(dobj, traceback.format_exc())) + warn('get_repo_link_template for {} failed:\n{}'.format(dobj, traceback.format_exc())) return None diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 20fe1064..18a06872 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -13,11 +13,11 @@ show_source_code = True # Provide links to source code online. - # online_source_link is a string whose str.format method is + # repo_link_template is a string whose str.format method is # called to template it for a given documentation object. # Supported keywords for interpolation are commit, path, start_line, and end_line. - # online_source_link = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' - online_source_link = None + # repo_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + repo_link_template = None # A prefix to use for every HTML hyperlink in the generated documentation. # No prefix results in all links being relative. diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index 1853d8d3..fbba47fa 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -2,7 +2,7 @@ import os import pdoc - from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_online_source_link + from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_repo_link_template def link(d, name=None, fmt='{}'): @@ -21,10 +21,10 @@ <%def name="ident(name)">${name} <%def name="show_source(d)"> - % if 'online_source_link' in locals() and online_source_link and d.source and d.obj is not getattr(d.inherits, 'obj', None): + % if repo_link_template and d.source and d.obj is not getattr(d.inherits, 'obj', None):
- Online source code + Online source code
%endif From 1dd84046135fe56dccfe4551d23995871d4771c2 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Tue, 3 Sep 2019 14:55:48 -0400 Subject: [PATCH 13/27] get_repo_link_template: get commit only if needed Refs https://stackoverflow.com/a/22830468/4651668 --- pdoc/html_helpers.py | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 47ed08b4..b85a8467 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -460,14 +460,28 @@ def get_repo_link_template(template: str, dobj: pdoc.Doc): Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working directory. """ + fields = _get_str_template_fields(template) try: - lines, start_line = inspect.getsourcelines(dobj.obj) - end_line = start_line + len(lines) + if 'commit' in fields: + commit = _get_head_commit() abs_path = inspect.getfile(dobj.obj) path = os.path.relpath(abs_path, os.getcwd()) # project-relative path - commit = _get_head_commit() + lines, start_line = inspect.getsourcelines(dobj.obj) + end_line = start_line + len(lines) url = template.format(**locals()) return url except Exception: warn('get_repo_link_template for {} failed:\n{}'.format(dobj, traceback.format_exc())) return None + + +@lru_cache() +def _get_str_template_fields(template): + """ + Return a list of field names in a template string for str.format. + """ + from string import Formatter + return [ + field_name for _, field_name, _, _ + in Formatter().parse(template) if field_name is not None + ] From 274b6d730b6cfab7e927fa8c08d0d4ead448f67b Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Tue, 3 Sep 2019 15:36:52 -0400 Subject: [PATCH 14/27] _project_relative_path function --- pdoc/html_helpers.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index b85a8467..386f1c3b 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -465,7 +465,7 @@ def get_repo_link_template(template: str, dobj: pdoc.Doc): if 'commit' in fields: commit = _get_head_commit() abs_path = inspect.getfile(dobj.obj) - path = os.path.relpath(abs_path, os.getcwd()) # project-relative path + path = _project_relative_path(abs_path) lines, start_line = inspect.getsourcelines(dobj.obj) end_line = start_line + len(lines) url = template.format(**locals()) @@ -475,6 +475,26 @@ def get_repo_link_template(template: str, dobj: pdoc.Doc): return None +@lru_cache() +def _project_relative_path(absolute_path): + """ + Convert an absolute path of a python source file to a project-relative path. + Assumes the project's path is either the current working directory or + Python library installation. + """ + from distutils.sysconfig import get_python_lib + for prefix_path in [os.getcwd(), get_python_lib()]: + common_path = os.path.commonpath([prefix_path, absolute_path]) + if common_path == prefix_path: + # absolute_path is a descendant of prefix_path + return os.path.relpath(absolute_path, prefix_path) + raise RuntimeError( + "absolute path {!r} is not a descendant of the current working directory " + "or of the system's python library." + .format(absolute_path) + ) + + @lru_cache() def _get_str_template_fields(template): """ From 4213b6dd75ad4226a1f7672cb66ddd383480885a Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Tue, 3 Sep 2019 16:01:40 -0400 Subject: [PATCH 15/27] Do not insert empty link --- pdoc/templates/html.mako | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index fbba47fa..b6faf145 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -22,11 +22,14 @@ <%def name="show_source(d)"> % if repo_link_template and d.source and d.obj is not getattr(d.inherits, 'obj', None): -
- - Online source code - -
+ <% repo_link = get_repo_link_template(repo_link_template, d) %> + % if repo_link: +
+ + Online source code + +
+ %endif %endif % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None):
From 83d3ffea7e91776927138968ecd2ba95dd252c85 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Tue, 3 Sep 2019 17:57:09 -0400 Subject: [PATCH 16/27] Show source / repo side-by-side display Co-authored-by: Vincent Rubinetti --- doc/build.sh | 1 + pdoc/html_helpers.py | 4 ++-- pdoc/templates/css.mako | 14 ++++++++++++++ pdoc/templates/html.mako | 34 +++++++++++++++++++--------------- 4 files changed, 36 insertions(+), 17 deletions(-) diff --git a/doc/build.sh b/doc/build.sh index a514ff49..fce45320 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -22,6 +22,7 @@ pushd "$DOCROOT/.." >/dev/null pdoc3 --html \ ${IS_RELEASE+--template-dir "$DOCROOT/pdoc_template"} \ --config "repo_link_template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \ + --config show_source_code=False \ --output-dir "$BUILDROOT" \ pdoc popd >/dev/null diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 386f1c3b..e58c9e8a 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -455,7 +455,7 @@ def _get_head_commit(): return None -def get_repo_link_template(template: str, dobj: pdoc.Doc): +def get_repo_link(template: str, dobj: pdoc.Doc): """ Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working directory. @@ -471,7 +471,7 @@ def get_repo_link_template(template: str, dobj: pdoc.Doc): url = template.format(**locals()) return url except Exception: - warn('get_repo_link_template for {} failed:\n{}'.format(dobj, traceback.format_exc())) + warn('get_repo_link_template for {} failed:\n{}'.format(dobj.obj, traceback.format_exc())) return None diff --git a/pdoc/templates/css.mako b/pdoc/templates/css.mako index 29c9a66d..04e31c18 100644 --- a/pdoc/templates/css.mako +++ b/pdoc/templates/css.mako @@ -204,6 +204,20 @@ text-transform: uppercase; cursor: pointer; } + .source summary div { + display: inline-flex; + align-items: center; + width: calc(100% - 20px); + } + .source summary div span:first-child { + flex-grow: 1; + text-align: left; + } + .repo-link { + display: block; + font-size: .8em; + text-transform: uppercase; + } .source pre { max-height: 500px; overflow: auto; diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index b6faf145..26bce978 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -2,7 +2,7 @@ import os import pdoc - from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_repo_link_template + from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_repo_link def link(d, name=None, fmt='{}'): @@ -21,22 +21,26 @@ <%def name="ident(name)">${name} <%def name="show_source(d)"> - % if repo_link_template and d.source and d.obj is not getattr(d.inherits, 'obj', None): - <% repo_link = get_repo_link_template(repo_link_template, d) %> - % if repo_link: -
- - Online source code - -
- %endif + % if d.source and d.obj is not getattr(d.inherits, 'obj', None): + % if repo_link_template: + <% repo_link = get_repo_link(repo_link_template, d) %> %endif - % if show_source_code and d.source and d.obj is not getattr(d.inherits, 'obj', None): -
- Expand source code - 
${d.source | h}
-
+ % if show_source_code: +
+ +
+ Expand source code + % if repo_link_template and repo_link: + View in Repo + %endif +
+ + 
${d.source | h}
+
+ % elif repo_link_template and repo_link: + View in Repo %endif + %endif <%def name="show_desc(d, short=False)"> From ca0e07ea96ebe5ede8fbc6294f3437afe015bf4d Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Sun, 8 Sep 2019 12:51:58 -0400 Subject: [PATCH 17/27] inspect.unwrap to fix double decorator error --- pdoc/html_helpers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index e58c9e8a..40a0842c 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -464,7 +464,7 @@ def get_repo_link(template: str, dobj: pdoc.Doc): try: if 'commit' in fields: commit = _get_head_commit() - abs_path = inspect.getfile(dobj.obj) + abs_path = inspect.getfile(inspect.unwrap(dobj.obj)) path = _project_relative_path(abs_path) lines, start_line = inspect.getsourcelines(dobj.obj) end_line = start_line + len(lines) From 5af382f5bb8281b138fca8ca0e6f407aa3dbd861 Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Sun, 8 Sep 2019 15:40:12 -0400 Subject: [PATCH 18/27] Update broken mathjax docs link --- pdoc/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pdoc/documentation.md b/pdoc/documentation.md index abbccb2a..62f2a9ac 100644 --- a/pdoc/documentation.md +++ b/pdoc/documentation.md @@ -192,7 +192,7 @@ or, alternatively, use [raw string literals]. [Google-style]: http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings [reST directives]: #supported-rest-directives [template config]: #custom-templates -[recognized delimiters]: http://docs.mathjax.org/en/latest/tex.html#tex-and-latex-math-delimiters +[recognized delimiters]: https://docs.mathjax.org/en/latest/input/tex/delimiters.html [raw string literals]: https://www.journaldev.com/23598/python-raw-string From 447cbf8fca7c6c6c0a1a9d251c9d3e8eed553336 Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 02:44:45 +0200 Subject: [PATCH 19/27] BUG: fix off-by-one error --- pdoc/html_helpers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 40a0842c..deb39954 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -467,7 +467,7 @@ def get_repo_link(template: str, dobj: pdoc.Doc): abs_path = inspect.getfile(inspect.unwrap(dobj.obj)) path = _project_relative_path(abs_path) lines, start_line = inspect.getsourcelines(dobj.obj) - end_line = start_line + len(lines) + end_line = start_line + len(lines) - 1 url = template.format(**locals()) return url except Exception: From 7d544bab03a45e2fd353f82052397bcc4835b91c Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 02:46:07 +0200 Subject: [PATCH 20/27] ENH: more robust project root dir detection. fallback to cwd --- pdoc/html_helpers.py | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index deb39954..a2d6004a 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -475,6 +475,23 @@ def get_repo_link(template: str, dobj: pdoc.Doc): return None +@lru_cache() +def _git_project_root(): + """ + Return the path to project root directory or None if indeterminate. + """ + path = None + for cmd in (['git', 'rev-parse', '--show-superproject-working-tree'], + ['git', 'rev-parse', '--show-toplevel']): + try: + path = subprocess.check_output(cmd, universal_newlines=True).rstrip('\r\n') + if path: + break + except (subprocess.CalledProcessError, OSError): + pass + return path + + @lru_cache() def _project_relative_path(absolute_path): """ @@ -483,7 +500,8 @@ def _project_relative_path(absolute_path): Python library installation. """ from distutils.sysconfig import get_python_lib - for prefix_path in [os.getcwd(), get_python_lib()]: + for prefix_path in (_git_project_root() or os.getcwd(), + get_python_lib()): common_path = os.path.commonpath([prefix_path, absolute_path]) if common_path == prefix_path: # absolute_path is a descendant of prefix_path From 4659cf947d5348b4ddf2785a96833aa9623515e2 Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 02:51:00 +0200 Subject: [PATCH 21/27] REF: shift code around just a bit --- pdoc/html_helpers.py | 54 ++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index a2d6004a..01e44a41 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -434,16 +434,35 @@ def extract_toc(text: str): return toc +def get_repo_link(template: str, dobj: pdoc.Doc): + """ + Interpolate `template` as a formatted string literal using values extracted + from `dobj` and the working environment. + """ + try: + if 'commit' in _str_template_fields(template): + commit = _git_head_commit() + abs_path = inspect.getfile(inspect.unwrap(dobj.obj)) + path = _project_relative_path(abs_path) + lines, start_line = inspect.getsourcelines(dobj.obj) + end_line = start_line + len(lines) - 1 + url = template.format(**locals()) + return url + except Exception: + warn('get_repo_link for {} failed:\n{}'.format(dobj.obj, traceback.format_exc())) + return None + + @lru_cache() -def _get_head_commit(): +def _git_head_commit(): """ If the working directory is part of a git repository, return the head git commit hash. Otherwise, raise a CalledProcessError. """ process_args = ['git', 'rev-parse', 'HEAD'] try: - commit = subprocess.check_output(process_args, universal_newlines=True) - return commit.strip() + commit = subprocess.check_output(process_args, universal_newlines=True).strip() + return commit except OSError as error: warn("git executable not found on system:\n{}".format(error)) except subprocess.CalledProcessError as error: @@ -455,26 +474,6 @@ def _get_head_commit(): return None -def get_repo_link(template: str, dobj: pdoc.Doc): - """ - Interpolate `template` as a formatted string literal using values extracted - from `dobj` and the working directory. - """ - fields = _get_str_template_fields(template) - try: - if 'commit' in fields: - commit = _get_head_commit() - abs_path = inspect.getfile(inspect.unwrap(dobj.obj)) - path = _project_relative_path(abs_path) - lines, start_line = inspect.getsourcelines(dobj.obj) - end_line = start_line + len(lines) - 1 - url = template.format(**locals()) - return url - except Exception: - warn('get_repo_link_template for {} failed:\n{}'.format(dobj.obj, traceback.format_exc())) - return None - - @lru_cache() def _git_project_root(): """ @@ -514,12 +513,13 @@ def _project_relative_path(absolute_path): @lru_cache() -def _get_str_template_fields(template): +def _str_template_fields(template): """ - Return a list of field names in a template string for str.format. + Return a list of `str.format` field names in a template string. """ from string import Formatter return [ - field_name for _, field_name, _, _ - in Formatter().parse(template) if field_name is not None + field_name + for _, field_name, _, _ in Formatter().parse(template) + if field_name is not None ] From cd8d401c36ec6154af3990715acabe79072d3efc Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 02:52:23 +0200 Subject: [PATCH 22/27] DOC: reword documentation, more example presets --- pdoc/templates/config.mako | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 18a06872..1692711b 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -12,11 +12,13 @@ # Disabling this can improve rendering speed of large modules. show_source_code = True - # Provide links to source code online. - # repo_link_template is a string whose str.format method is - # called to template it for a given documentation object. - # Supported keywords for interpolation are commit, path, start_line, and end_line. - # repo_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + # If set, format links to objects in online source code repository + # according to this template. Supported keywords for interpolation + # are: commit, path, start_line, end_line. + #repo_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + #repo_link_template = 'https://gitlab.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + #repo_link_template = 'https://bitbucket.org/USER/PROJECT/src/{commit}/{path}#lines-{start_line}:{end_line}' + #repo_link_template = 'https://CGIT_HOSTNAME/PROJECT/tree/{path}?id={commit}#n{start-line}' repo_link_template = None # A prefix to use for every HTML hyperlink in the generated documentation. From b1da5fd8334e9cbfaaf7b1e2c4941a750ab33d29 Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 04:17:17 +0200 Subject: [PATCH 23/27] REF: modify html/css --- pdoc/html_helpers.py | 2 ++ pdoc/templates/css.mako | 26 ++++++++++---------------- pdoc/templates/html.mako | 16 ++++++---------- 3 files changed, 18 insertions(+), 26 deletions(-) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 01e44a41..5712752d 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -439,6 +439,8 @@ def get_repo_link(template: str, dobj: pdoc.Doc): Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working environment. """ + if not template: + return None try: if 'commit' in _str_template_fields(template): commit = _git_head_commit() diff --git a/pdoc/templates/css.mako b/pdoc/templates/css.mako index 04e31c18..5d9c31c1 100644 --- a/pdoc/templates/css.mako +++ b/pdoc/templates/css.mako @@ -196,28 +196,22 @@ background: inherit; /* Don't grey-back parameters */ } - .source summary { + .source summary, + .repo-link-div { color: #666; text-align: right; font-weight: 400; font-size: .8em; text-transform: uppercase; - cursor: pointer; - } - .source summary div { - display: inline-flex; - align-items: center; - width: calc(100% - 20px); - } - .source summary div span:first-child { - flex-grow: 1; - text-align: left; - } - .repo-link { - display: block; - font-size: .8em; - text-transform: uppercase; } + .source summary > * { + white-space: nowrap; + cursor: pointer; + } + .repo-link { + color: inherit; + margin-left: 1em; + } .source pre { max-height: 500px; overflow: auto; diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index 26bce978..02173fb5 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -21,24 +21,20 @@ <%def name="ident(name)">${name} <%def name="show_source(d)"> - % if d.source and d.obj is not getattr(d.inherits, 'obj', None): - % if repo_link_template: - <% repo_link = get_repo_link(repo_link_template, d) %> - %endif + % if (show_source_code or repo_link_template) and d.source and d.obj is not getattr(d.inherits, 'obj', None): + <% repo_link = get_repo_link(repo_link_template, d) %> % if show_source_code:
-
Expand source code - % if repo_link_template and repo_link: - View in Repo + % if repo_link: + Browse repo %endif - 
${d.source | h}
- % elif repo_link_template and repo_link: - View in Repo + % elif repo_link: +
Browse repo
%endif %endif From 29ec805bb3f8ca993fe8dc5ee9c9c17bc2505315 Mon Sep 17 00:00:00 2001 From: Kernc Date: Sat, 14 Sep 2019 04:27:25 +0200 Subject: [PATCH 24/27] MNT: move pdoc config overrides into a config.mako file --- doc/build.sh | 2 -- doc/pdoc_template/config.mako | 5 +++++ 2 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 doc/pdoc_template/config.mako diff --git a/doc/build.sh b/doc/build.sh index fce45320..70899edb 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -21,8 +21,6 @@ rm -r "$BUILDROOT" 2>/dev/null || true pushd "$DOCROOT/.." >/dev/null pdoc3 --html \ ${IS_RELEASE+--template-dir "$DOCROOT/pdoc_template"} \ - --config "repo_link_template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \ - --config show_source_code=False \ --output-dir "$BUILDROOT" \ pdoc popd >/dev/null diff --git a/doc/pdoc_template/config.mako b/doc/pdoc_template/config.mako new file mode 100644 index 00000000..fb592a21 --- /dev/null +++ b/doc/pdoc_template/config.mako @@ -0,0 +1,5 @@ +<%! + +repo_link_template = 'https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}' + +%> From 8edf3fe7db71c35eecc970fde162662f00df38da Mon Sep 17 00:00:00 2001 From: Daniel Himmelstein Date: Mon, 16 Sep 2019 12:06:15 -0400 Subject: [PATCH 25/27] TST: get_repo_link on example module --- pdoc/test/__init__.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/pdoc/test/__init__.py b/pdoc/test/__init__.py index 72af83f2..bed03a87 100644 --- a/pdoc/test/__init__.py +++ b/pdoc/test/__init__.py @@ -3,6 +3,7 @@ """ import inspect import os +import shutil import signal import sys import threading @@ -26,7 +27,7 @@ from pdoc.cli import main, parser from pdoc.html_helpers import ( minify_css, minify_html, glimpse, to_html, - ReferenceWarning, extract_toc, + ReferenceWarning, extract_toc, get_repo_link, ) TESTS_BASEDIR = os.path.abspath(os.path.dirname(__file__) or '.') @@ -790,6 +791,16 @@ def test_extract_toc(self): toc = extract_toc(text) self.assertEqual(toc, expected) + @unittest.skipIf(shutil.which("git") is None, reason="test assumes git installed on system") + def test_get_repo_link(self): + url = get_repo_link( + template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}', + dobj=pdoc.Module(EXAMPLE_MODULE).find_ident('module.foo'), + ) + self.assertIsNotNone(url) + expect_pattern = r"https://github.com/pdoc3/pdoc/blob/[0-9a-f]{40}/pdoc/test/example_pkg/module.py#L19-L21" # noqa E501 + self.assertRegex(url, expect_pattern) + class Docformats(unittest.TestCase): @classmethod From b5fd1edf4042055d872846f11d432b72b975fe7c Mon Sep 17 00:00:00 2001 From: Kernc Date: Thu, 26 Sep 2019 23:58:42 +0200 Subject: [PATCH 26/27] REF: "repo_link" -> "git_link"; "Browse git" :-=) --- doc/pdoc_template/config.mako | 2 +- pdoc/html_helpers.py | 4 ++-- pdoc/templates/config.mako | 10 +++++----- pdoc/templates/css.mako | 4 ++-- pdoc/templates/html.mako | 14 +++++++------- pdoc/test/__init__.py | 6 +++--- 6 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/pdoc_template/config.mako b/doc/pdoc_template/config.mako index fb592a21..577094b8 100644 --- a/doc/pdoc_template/config.mako +++ b/doc/pdoc_template/config.mako @@ -1,5 +1,5 @@ <%! -repo_link_template = 'https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}' +git_link_template = 'https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}' %> diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 5712752d..2580d74d 100644 --- a/pdoc/html_helpers.py +++ b/pdoc/html_helpers.py @@ -434,7 +434,7 @@ def extract_toc(text: str): return toc -def get_repo_link(template: str, dobj: pdoc.Doc): +def format_git_link(template: str, dobj: pdoc.Doc): """ Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working environment. @@ -451,7 +451,7 @@ def get_repo_link(template: str, dobj: pdoc.Doc): url = template.format(**locals()) return url except Exception: - warn('get_repo_link for {} failed:\n{}'.format(dobj.obj, traceback.format_exc())) + warn('format_git_link for {} failed:\n{}'.format(dobj.obj, traceback.format_exc())) return None diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index 1692711b..6e48c097 100644 --- a/pdoc/templates/config.mako +++ b/pdoc/templates/config.mako @@ -15,11 +15,11 @@ # If set, format links to objects in online source code repository # according to this template. Supported keywords for interpolation # are: commit, path, start_line, end_line. - #repo_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' - #repo_link_template = 'https://gitlab.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' - #repo_link_template = 'https://bitbucket.org/USER/PROJECT/src/{commit}/{path}#lines-{start_line}:{end_line}' - #repo_link_template = 'https://CGIT_HOSTNAME/PROJECT/tree/{path}?id={commit}#n{start-line}' - repo_link_template = None + #git_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + #git_link_template = 'https://gitlab.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}' + #git_link_template = 'https://bitbucket.org/USER/PROJECT/src/{commit}/{path}#lines-{start_line}:{end_line}' + #git_link_template = 'https://CGIT_HOSTNAME/PROJECT/tree/{path}?id={commit}#n{start-line}' + git_link_template = None # A prefix to use for every HTML hyperlink in the generated documentation. # No prefix results in all links being relative. diff --git a/pdoc/templates/css.mako b/pdoc/templates/css.mako index 5d9c31c1..f82ffc9e 100644 --- a/pdoc/templates/css.mako +++ b/pdoc/templates/css.mako @@ -197,7 +197,7 @@ } .source summary, - .repo-link-div { + .git-link-div { color: #666; text-align: right; font-weight: 400; @@ -208,7 +208,7 @@ white-space: nowrap; cursor: pointer; } - .repo-link { + .git-link { color: inherit; margin-left: 1em; } diff --git a/pdoc/templates/html.mako b/pdoc/templates/html.mako index 02173fb5..a108153a 100644 --- a/pdoc/templates/html.mako +++ b/pdoc/templates/html.mako @@ -2,7 +2,7 @@ import os import pdoc - from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, get_repo_link + from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, format_git_link def link(d, name=None, fmt='{}'): @@ -21,20 +21,20 @@ <%def name="ident(name)">${name} <%def name="show_source(d)"> - % if (show_source_code or repo_link_template) and d.source and d.obj is not getattr(d.inherits, 'obj', None): - <% repo_link = get_repo_link(repo_link_template, d) %> + % if (show_source_code or git_link_template) and d.source and d.obj is not getattr(d.inherits, 'obj', None): + <% git_link = format_git_link(git_link_template, d) %> % if show_source_code:
Expand source code - % if repo_link: - Browse repo + % if git_link: + Browse git %endif 
${d.source | h}
- % elif repo_link: -
Browse repo
+ % elif git_link: +
Browse git
%endif %endif diff --git a/pdoc/test/__init__.py b/pdoc/test/__init__.py index bed03a87..b126852f 100644 --- a/pdoc/test/__init__.py +++ b/pdoc/test/__init__.py @@ -27,7 +27,7 @@ from pdoc.cli import main, parser from pdoc.html_helpers import ( minify_css, minify_html, glimpse, to_html, - ReferenceWarning, extract_toc, get_repo_link, + ReferenceWarning, extract_toc, format_git_link, ) TESTS_BASEDIR = os.path.abspath(os.path.dirname(__file__) or '.') @@ -792,8 +792,8 @@ def test_extract_toc(self): self.assertEqual(toc, expected) @unittest.skipIf(shutil.which("git") is None, reason="test assumes git installed on system") - def test_get_repo_link(self): - url = get_repo_link( + def test_format_git_link(self): + url = format_git_link( template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}', dobj=pdoc.Module(EXAMPLE_MODULE).find_ident('module.foo'), ) From 5f0d508f34351a868771c71959bd1ca3b1dc1055 Mon Sep 17 00:00:00 2001 From: Kernc Date: Fri, 27 Sep 2019 00:03:20 +0200 Subject: [PATCH 27/27] TST: robuster regex --- pdoc/test/__init__.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pdoc/test/__init__.py b/pdoc/test/__init__.py index b126852f..d52e75bc 100644 --- a/pdoc/test/__init__.py +++ b/pdoc/test/__init__.py @@ -797,9 +797,8 @@ def test_format_git_link(self): template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}', dobj=pdoc.Module(EXAMPLE_MODULE).find_ident('module.foo'), ) - self.assertIsNotNone(url) - expect_pattern = r"https://github.com/pdoc3/pdoc/blob/[0-9a-f]{40}/pdoc/test/example_pkg/module.py#L19-L21" # noqa E501 - self.assertRegex(url, expect_pattern) + self.assertRegex(url, r"https://github.com/pdoc3/pdoc/blob/[0-9a-f]{40}" + r"/pdoc/test/example_pkg/module.py#L\d+-L\d+") class Docformats(unittest.TestCase):