Fix several GitHub code linking problems and add unit tests.

Review Request #12532 — Created Aug. 14, 2022 and submitted — Latest diff uploaded

Information

beanbag-docutils
master

Reviewers

We had a Python 3 incompatibility issue where a byte string was ending
up in the format string for the final URL when linking to code on
GitHub, resulting in bad links. The source of the problem turned out to
be in _get_git_doc_ref(), which accepted the resulting byte string
from _run_git() and passed it along.

This issue was first found by Simon Willison, who helpfully provided a
pull request (https://github.com/beanbaginc/beanbag-docutils/pull/2) for
this problem.

The lack of test coverage caused us to miss this issue. In the
development of new tests, additional problems were found. Due to the way
we attempted to generate links to code, we failed to link properly to
variables, and could end up linking to the wrong page if a variable was
assigned to an object, class, or function reference.

The reason is that we were walking an object path (a.b.c.d), and
assuming that the last item (d) was something that resided owned by
the module. Instead, for variables, fetching d really just fetched the
value of the variable. That caused the resulting link to point to the
wrong place entirely, and that place could be a 404, due to how links
are generated.

The better solution is to avoid the inspect machinery we were using,
which can't deal with this situation, and instead parse the AST of the
file. Through this, we can reliably look up the identifier belonging to
the module and get the resulting line number.

This change incorporates that along with the fix for byte strings,
bringing Python 3.6-3.11 compatibility for this module (we will be
dropping 2.7 from beanbag-docutils 2.0).

All unit tests pass.

Built the Review Board docs, and verified that all the broken links I
could reproduce (including ones pointing to the wrong places) were now
correctly pointing to the correct files and line numbers on GitHub.

Commits

Files