2

Background

I'm designing a Sphinx extension called sphinx-uml that tries to improve sphinx-pyreverse. The goal is to output a navigable UML diagram (when you click a class/method/function, you go to the right documentation page).

Problem

In a Sphinx extension, how to resolve the URL of an arbitrary class/method/function (programmatically, during the build process)?

Attempts

Currently, I have a naive heuristic to rebuild those URLs, assuming that any class/method is documented by in the HTML build directory populated by Sphinx. It allows to craft such SVG diagrams (see here). Currently, I use this link when crafting the Graphviz node but this has the following limitations:

  • classes that do not belong to the package get a (invalid) link (they should be resolved using graphviz.ext.intersphinx or not resolved),
  • this heuristic depends on the naming conventions adopted by sphinx-build.

I know that graphviz.ext.inheritance_diagram can link its graphviz vertices to the right documentation using pending xrefs, but I don't understand how it works and how to leverage it in my own code.

I guess that graphviz.ext.intersphinx uses similar mechanisms to use the right link.

Improve this question
4
  • 1
    Sphinx would initially output the rst/HTML structure automatically based on sphinx-apidoc when you first run it (at present if you customize anything in your .rst the sphinx-apidoc tool wouldn't merge changes on subsequent runs) and unless you customize the templates the file/anchor structure you'd get would be fixed. Commented Jun 30 at 22:03
  • Here comes the conf.py hacking, when you ask: "How to determine, in a Sphinx extension, how to resolve the URL of an arbitrary class/method/function?" that's a complex question! Somewhere in extending Sphinx you should find a link to the event handlers that can be used to determine the URL/anchor of the object being documented. Anyway, I do by hand what you're proposing to automate, the main drawback being that it needs to be maintained manually but since graphviz's automatic layout isn't to my satisfaction it's a middle ground Commented Jun 30 at 22:09
  • 2
    The "naming conventions" you mention are fixed for the HTML builder, generally the anchor will be doc.rst#fully.qualified.name. Notice that the doc.rst part is supposed to be arbitrated by the documentation author, with the anchor being fixed. So your question is simply: how to get the URL programmatically during the build process? Commented Jul 1 at 0:13
  • 1
    So your question is simply: how to get the URL programmatically during the build process? : Yes, exactly. Updated my question. As I said, graphviz.ext.inheritance_diagram seems to do so for class names but I don't understand how it works and how to adapt/extend it to my case. Commented Jul 1 at 12:43
Related questions
4
Is it possible using sphinx to link to a specific URL using the :class: role?
4
How to specifiy an alias for a Python class/attribute/constants/method in Sphinx?
9
Can sphinx validate documentation against the actual implementation
Load 6 more related questions Show fewer related questions

0

Reset to default

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.