Open lamourj opened 5 years ago
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? :thinking:
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!
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?
__subclasses__
to get what we need?Given such a list or whatever, using it seems to merely be a matter of changing this method:
https://docs.python.org/3/library/<module>.html
https://docs.python.org/3/library/<module>.html#<identifier>
https://numpy.org/doc/stable/reference/generated/<identifier>.html
https://docs.scipy.org/doc/scipy/reference/<module>.html
https://docs.scipy.org/doc/scipy/reference/generated/<identifier>.html
https://pandas.pydata.org/docs/reference/api/<identifier>.html
matplotlib.<module>
becomes https://matplotlib.org/api/<module>_api.html
https://matplotlib.org/api/_as_gen/<identifier>.html
https://seaborn.pydata.org/generated/<identifier>.html
https://pdoc3.github.io/pdoc/doc/pdoc/<module>.html#<identifier>
https://pdoc3.github.io/pdoc/doc/pdoc/#<identifier>
<identifier>
: the full identifier/refname, e.g. scipy.stats.cauchy
or itertools.starmap
<module>
: the module nameWould it also be nice to allow common abbreviations?
Package | Abbr |
---|---|
numpy | np |
pandas | pd |
matplotlib | mpl |
matplotlib.pyplot ? | plt |
seaborn | sns |
Here's a commit that implements this as part of a custom theme (see also its errata/addendums):
It seems to work quite well: https://nekokatt.github.io/hikari/hikari/embeds.html#hikari.embeds.Embed
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.
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?
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.
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:
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