Link to class not created without the --external-links option

[mikecharles]

I'm generating documentation for my data_utils package. Under data_utils.gridded.grid I have a class defined:

class Grid:
    """
    ...
    """
    def __init__(...)

But when I generate documentation with this command:

pdoc data_utils --overwrite --html --html-dir docs/api

Any references in modules' docstrings (ex. data_utils.gridded.plotting) to data_utils.gridded.grid.Grid do not become links. However, when I include the --external-links arg:

pdoc data_utils --overwrite --external-links --html --html-dir docs/api

data_utils.gridded.grid.Grid does become a link. So why is this considered "external"?

[BurntSushi]

Unfortunately, links don't work that well in statically generated docs. I think they should work just fine for linking within the same module, but linking to things in other modules or sub-modules just doesn't work right now.

The "external" links stuff only applies when documentation is served over HTTP. In that case, it employs a hack where links to items in other modules are specially written. When you follow them, the HTTP server tries to resolve them dynamically by search all modules in sys.path.

In essence, the current (automatic) linking is very simplistic.