Hyperlinks to external official documentation

[lamourj]

Expected Behavior

When using -c show_types_annotations (found in #6), hyperlinks to external references should be added not only on the method declaration but also in the doc below (that is my understanding from https://pdoc3.github.io/pdoc/doc/pdoc/#linking-to-other-identifiers).

Actual Behavior and steps to reproduce

Example:

def example_method(a: datetime) -> int:
    """

    Parameters
    ----------
    a : `datetime.datetime`
        A date.

    Returns
    -------
    `int`
        The day.
    """

    return a.day

While the page renders as follows:

if using --http. When using --html, type hints are even completely omitted :

I guess the proper behavior would be to have the hyperlinks both in the method declaration in the first line and in the text below.
Moreover, it would likely be ideal to link to the official documentation, such as this for datetime

Additional info

• pdoc version: 0.6.3

[kernc]

Example:

The first is an issue of incorrect formatting. Numpydoc syntax is:

Parameters
----------
a : datetime.datetime
    A date.

Returns
-------
type_without_backticks
    The day.

After you fix that, your symbols should be linked.

I guess we could be lenient towards extra enclosing backticks. How does Sphinx handle that? 🤔

Moreover, it would likely be ideal to link to the official documentation, such as this for datetime

Extenal links only "work" in --http mode. The integrated webserver translates URLs such as /datetime.datetime.ext into likely candidate modules and pdoc-docs them on the fly.

Ideally, we would link to official module docs, very much agreed!

Design discussion + PR welcome!

[MPvHarmelen]

It seems like this is quite easily implemented, given some list of modules and a way to get a url from an identifier.

Preferably this list is easily extendible. What what be a good way of doing that?

• some class magic with an abstract base class and using __subclasses__ to get what we need?
• a module level mapping that is initialised upon import and can be queried?
• something cleaner than both of the above?

Given such a list or whatever, using it seems to merely be a matter of changing this method:

pdoc/pdoc/__init__.py

Lines 1418 to 1422 in 098208c

	def url(self, *args, **kwargs):
	"""
	`External` objects return absolute urls matching `/{name}.ext`.
	"""
	return '/%s.ext' % self.name

[MPvHarmelen]

External things and their url format

• Python's built-in modules:
  • module: https://docs.python.org/3/library/<module>.html
  • module contents: https://docs.python.org/3/library/<module>.html#<identifier>
• numpy: https://numpy.org/doc/stable/reference/generated/<identifier>.html
• scipy:
  • for modules: https://docs.scipy.org/doc/scipy/reference/<module>.html
  • other things https://docs.scipy.org/doc/scipy/reference/generated/<identifier>.html
• pandas: https://pandas.pydata.org/docs/reference/api/<identifier>.html
• matplotlib:
  • for modules matplotlib.<module> becomes https://matplotlib.org/api/<module>_api.html
  • other things: https://matplotlib.org/api/_as_gen/<identifier>.html
• seaborn: https://seaborn.pydata.org/generated/<identifier>.html
• pdoc3:
  • sub-modules and all stuff in them: https://pdoc3.github.io/pdoc/doc/pdoc/<module>.html#<identifier>
  • main stuff: https://pdoc3.github.io/pdoc/doc/pdoc/#<identifier>

Legend

• <identifier>: the full identifier/refname, e.g. scipy.stats.cauchy or itertools.starmap
• <module>: the module name

Abbreviations

Would it also be nice to allow common abbreviations?

Package	Abbr
numpy	np
pandas	pd
matplotlib	mpl
matplotlib.pyplot ?	plt
seaborn	sns

abbreviations used in the numpy documentation

[MPvHarmelen]

Attempt at getting a list of all built-in packages

[kernc]

Here's a commit that implements this as part of a custom theme (see also its errata/addendums):

hikari-py/hikari@bbc50ae#diff-61a427a12a765e10e5942cd1c2c64af0

It seems to work quite well: https://nekokatt.github.io/hikari/hikari/embeds.html#hikari.embeds.Embed

[joshorr]

I have private libraries/modules that I use pdoc3 on, and I would like to link to this from other projects. I publish the documentation at a private location for these libraries/modules. It would be really nice to be able to provide a mapping to the private external libraries published documentation from these other projects docs.

Is there anyway easily customize what def url(self, *args, **kwargs): returns while still using the default theme [ie: non-custom]? I just need a simple way to tell pdoc3 the base URL for a specific external python module.

[K20shores]

Forgive my ignorance, but it seems like there is no way to link to external websites. I want to link the matplotlib axes documentation. Is there no way to do this?

[sawatts]

Just for comparison: We use doxygen to generated the docsets for C/C++ libraries, which are published internally. Doxygen can generate a Tag File which provides relative links to symbols within the docset. These are a simple XML format,

The configuration file can use the tag files from external projects, along with their base URLs, to generate inter-docset links. I also discovered that these cross-links can go both ways - from dependency to dependent, and visa versa (i.e. class diagrams in the base class started showing derived classes from dependent libraries - not something that was documented!).

For example, I recently added a filter to support cmake-language, and as part of this I synthesized a tag file for cmake's online documentation, such that doxygen autogenerates links from symbol mentions to the external documentation.

Doxygen also generates docsets from python doc comments - but that's another topic...

The first step for cross linking would be for pdoc to generate a tag file mapping symbols to relative links; then solve for using that information to generate links to external packages. Using the same tagfile format as doxygen would be useful across the domain.