document linking scheme; spawn more tickets

[andy-maier]

Hi,
I am having trouble getting pdoc to create links to modules from within sub-modules of a package.

Example:

1. File foo/init.py:

"""
Package foo:

  * The `bar` module (no link)
  * The `.bar` module (no link)
  * The `foo.bar` module (link -> ok)
"""

__all__ = ["bar", "baz"]

1. File foo/bar.py:

"""
Module bar:

  * The `baz` module (no link)
  * The `.baz` module (no link)
  * The `foo.baz` module (link when shown on foo package page -> ok; No link when shown on foo.bar module page -> issue #1)
  * The `foo` package (no link -> issue #2)
  * The `..foo` package (no link)
"""

class Bar(object):
    pass

1. File foo/baz.py:

"""
Module baz
"""

class Baz(object):
    pass

The pdoc documentation states that links need to be start with the package. In doing so, the link to 'foo.baz' in sub-module 'bar' is generated as a link in the version of sub-module 'bar' that is shown on the 'foo' page. However, on the 'foo.bar' page, the link to 'foo.baz' is formatted with monospace font, but is not generated as a link (marked as issue #1 in the code above).

Second, the link to the package 'foo' in sub-module 'foo.bar' is not generated as a link either (marked as issue #2 in the code above).

I have added some more variations, just to try them out.

Is there a documentation about the link generation by pdoc, and more generally, about which flavor of markdown it supports?

Regards,
Andy

[BurntSushi]

Link generation basically has two modes. The first mode is used when you ask for the static HTML docs of a Python module, and it sounds like that's what you're doing here. It has very limited support for linking. It basically only works for things inside the module that is being documented. The second mode is invoked only when you serve documentation from pdoc as an HTTP server. It creates things called "external links" that are resolved dynamically. That may help you fix things here, but it obviously removes the nice properties of just having static HTML.

I'm going to change this ticket to "document linked; spawn more tickets" with the idea being that once I document the existing scheme in enough detail, it will be more clear what has to be done to improve the state of affairs.