Support for online source links

[dhimmel]

Closes #100

[dhimmel]

Currently, our path detection for a .py does not work when pdoc receives an installed module rather than a relative directory as input. As per the logs, we get links like;

ERROR: broken link in pdoc/html_helpers.html:  https://github.com/pdoc3/pdoc/blob/99a69a843aabf1788e5f0af755df7f183a36f5a6/../../../virtualenv/python3.6.7/lib/python3.6/site-packages/pdoc/html_helpers.py

@kernc any idea on how we could get the path of the package root regardless of whether the user passes a "import path resolvable in the current environment, or a file path to a Python module or package." Currently, the broken implementation is:

pdoc/pdoc/html_helpers.py

Lines 455 to 456 in af15129

	abs_path = inspect.getmodule(dobj.obj).__file__
	path = os.path.relpath(abs_path, os.getcwd()) # project-relative path

[kernc]

Yeah, that was the fragile part. Thinking ... 🤔

[dhimmel]

Local testing command:

pdoc3 --force --html \
  --template-dir doc/pdoc_template \
  --output-dir doc \
  --config "repo_link_template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}'" \
  pdoc

Currently dealing with error

TypeError: <functools._lru_cache_wrapper object at 0x7f172f2e6ac8> is not a module, class, method, function, traceback, frame, or code object

related to inspecting a decorated method I believe

[dhimmel]

Okay as of 4213b6d we get a warning related to a malfunction. I modified html.mako to only show the repo link if it evaluates as True. Therefore, the resulting docs look good although there may be a missing link somewhere.

[dhimmel]

The double decoration of this function is what is causing the TypeError in inspect.getfile:

pdoc/pdoc/__init__.py

Lines 415 to 426 in 9d71e32

	@property # type: ignore
	@lru_cache()
	def source(self) -> str:
	"""
	Cleaned (dedented) source code of the Python object. If not
	available, an empty string.
	"""
	try:
	lines, _ = inspect.getsourcelines(self.obj)
	except (ValueError, TypeError, OSError):
	return ''
	return inspect.cleandoc(''.join(['\n'] + lines))

[vincerubinetti]

@dhimmel you'll probably want to add text-align: right to the repo-link class to keep it on the same side as when it is inside a <summary>

[kernc]

The double decoration of this function is what is causing the TypeError in inspect.getfile

As a workaround, inspect.unwrap() before getfile() ought to resolve that.

[dhimmel]

Okay I think the HTML output functionality is now working. I've checked the possible combinations of show_source_code and repo_link_template. They render properly (side-by-side) in FireFox. The only iffy behavior is on small screens when the text wraps lines:

But this is probably not a huge deal? BTW hat tip to @vincerubinetti for all the CSS help.

[dhimmel]

@kernc ready for your review.

[vincerubinetti]

@dhimmel that can be fixed with some @media query CSS if you want.

[dhimmel]

that can be fixed with some @media query CSS if you want.

If it's straightforwards and not too ugly, then sure!

[kernc]

I apologize for the long turnaround. I find wholly too little productive screen time these days.

Pushed are some touch-ups I like. What do you think?

[kernc]

Hmmm, a simple unit test would be nice. 🤔

pdoc/pdoc/test/__init__.py

Line 727 in 6443c91

class HtmlHelpersTest(unittest.TestCase):

[dhimmel]

Pushed are some touch-ups I like. What do you think?

Beautiful.

a simple unit test would be nice

_git_head_commit, _git_project_root, _project_relative_path seem hard to test because their behavior is system-specific. get_repo_link is what we probably care about most for testing, but that depends on the three-system specific functions. Any recommendations about how to proceed with tests?

[kernc]

I think assuming a Travis-like environment (i.e. with git) is enough. Just something that roughly covers.

[dhimmel]

I think assuming a Travis-like environment (i.e. with git) is enough. Just something that roughly covers.

Okay test_get_repo_link added in 8edf3fe.

[kernc]

Will try to get this in and published in the next few days.

[dhimmel]

Will try to get this in and published in the next few days.

Not to rush you, just a reminder! 😈

[kernc]

Was just waiting for @rjmill in #101 since that also introduces a breaking change suiting a version bump. No problem. 😅

Thanks for this lovely addition. Released in 0.7.0.