3

I'm using Sphinx to document a python package that wraps a proprietary API that wasn't documented using Sphinx as far as I can tell. The API documentation provides useful information, but the URL's are not in a format that sphinx can automatically generate links for. Is it possible to mark a string semantically as a class, while specifying the link target by hand?

I tried:

:class:`Class <https://api.documentation/some/path/to_class_constructor.htm>`_

but this raises a WARNING: Mismatch: both interpreted text role prefix and reference suffix.. Then I also tried

:class:`Class <https://api.documentation/some/path/to_class_constructor.htm>`

which doesn't raise a warning, but doesn't generate a hyperlink either.

As per Steve Piercy's comment below, the sphinx.ext.extlinks extension keeps the documentation a little cleaner, but it looses its semantic meaning, which I would prefer to keep.

Is it possible to somehow show the text references a class, and at the same time links to the external API documentation?

mzjn
  • 48,958
  • 13
  • 128
  • 248
hugovdberg
  • 1,461
  • 13
  • 24
  • 1
    Is the external API documentation generated by Sphinx? If so, then you can use [intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html). Otherwise you can set a base URL with [extlinks](https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html). – Steve Piercy Aug 19 '19 at 09:04
  • Follow up: see my [comment on a recently asked question](https://stackoverflow.com/questions/57569177/sphinx-multiple-nested-roles). Ideally the remote documentation was generated by Sphinx and would support intersphinx and its styles. – Steve Piercy Aug 20 '19 at 10:26

0 Answers0