Fix hyperlinking and other HTML stuff #177
Conversation
This reverts commit 6b0b0c3. Compared to Python-Markdown, which is [maintained], Markdown2 is [bug-ridden]. Incorrectly renders at least: [`code`](links) which is important for us. The owner seems to [think it] an edge case despite numerous such reports. Python-Markdown has [12k dependents] whereas Markdown2 has [only 1.3k], making the former's community quite a bit larger. Finally, the [initial reason] for switch to Markdown2 was its handling of fenced code blocks (with an addon). But Python-Markdown supports this case just the same, with an addon. [maintained]: https://github.com/Python-Markdown/markdown/issues [bug-ridden]: https://github.com/trentm/python-markdown2/issues [think it]: trentm/python-markdown2#259 [12k dependents]: https://libraries.io/pypi/Markdown/usage [only 1.3k]: https://libraries.io/pypi/markdown2/usage [initial reason]: #119
| return _pdoc.get("%s.%s" % (self.name, name), False) is None | ||
|
|
||
| def exported(name): | ||
| exported = name == "__init__" or _is_exported(name) | ||
| return not forced_out(name) and exported | ||
| inheried = name not in self.cls.__dict__ |
There was a problem hiding this comment.
This now skips listing inherited members that have not been overridden. E.g.
class C:
def f(self): pass
def g(self): pass
class D(C):
def g(self): pass
def h(self): passHere for D, only g() and h() will be documented, while for C, f() and g().
The rationale is one can look into hyperlinked ancestors for the inherited members, less repetition etc.
Even though it looks quite pretty in the project I'm working with, I imagine not all projects would like/expect this. Can be made a setting if __pdoc__ "protocol" is extended. Please advise.
| @@ -145,18 +147,20 @@ def lookup(module, refname, link_prefix): | |||
| return None, None | |||
| if isinstance(d, pdoc.doc.Module): | |||
| return d.refname, module_url(module, d, link_prefix) | |||
| suffix = '()' if isinstance(d, pdoc.doc.Function) else '' | |||
| name = d.qualname if get_qualname else d.name | |||
There was a problem hiding this comment.
Function references are by default labeled with their full qualified name, e.g. C.f or D.g in case of methods. Previously, it was the whole refname (module.submodule.submodule.whole.hierarchy.class.method). I think this is better, YMMV. Open to discussion.
Before when these helpers were part of the HTML template, it was much easier to override them (and specify --template-dir).
|
Happy to add tests once the premises are agreed upon. Interestingly, current tests all pass when ran locally (edit: only in PyCharm). |
|
Closed in favor of #182. Should anyone want to continue, welcome. |
The commits seem disjoint, but really are just a series of patches that pretty much restores (and a bit builds upon) the previous HTML output behavior.
Please see commits individually.
Changes of note:
Of course, everything is open to discussion.