No Hyperlinks for Pydantic Types

[tahoward]

Running Sphinx 4.1.1 and pydantic 1.8.2.

Enabled extensions:

    'sphinx.ext.autodoc',
    'sphinxcontrib.autodoc_pydantic',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints'

Sample:

from pydantic import BaseModel


class TestClass:
    """Test

    Attributes:
        model (TestModel): Model
    """

    def __init__(self):
        self.model = TestModel()


class TestModel(BaseModel):
    pass

The generated document will not have a hyperlink for the TestModel data type reference. Removing the BaseModel class from TestModel renders the type references with hyperlinks again.

[mansenfranzen]

Thanks for the bug report. I could reproduce the issue myself using the .. automodule:: directive for documenting your test code. The hyperlinks work with pydantic models if autodoc_pydantic is deactivated - so this is definately a bug. This probably occurs due to the custom directives autodoc_pydantic uses. I will take a look at it.

[mansenfranzen]

@tahoward The bug was related to how typed field references work. They always use the class role. Until now, autodoc_pydantic objects could not be referenced by the class role. However, this should be the case and it totally makes sense because pydantic models/settings are python classes.

Before merging the related PR, it would be great if you could test the bug fix on your site to confirm that my test case did indeed capture the incorrect behavior which you've encountered. To do so, please install the current dev release in your doc-building-environment via pip install git+git://github.com/mansenfranzen/[email protected] and rebuild your docs.

[StephenHogg]

I have this problem too, it turns out - just tried with that release and no dice, unfortunately.

[mansenfranzen]

@StephenHogg thanks for joining the conversation. I just rechecked if I accidentally messed up the v1.3.2-a.1 but it looks good. The following setup works fine for me with v1.3.2-a.1:

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

project = 'Test'
copyright = 'Test'
author = 'Test'

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.autodoc_pydantic',
    'sphinx.ext.napoleon',
]

test.py

from pydantic import BaseModel


class TestClass:
    """Test

    Attributes:
        model (TestModel): Model
    """

    def __init__(self):
        self.model = TestModel()


class TestModel(BaseModel):
    pass

index.rst

.. automodule:: test
   :members:
   :undoc-members:

The generated doc strings contains the a link from the doc string body of TestClass to TestModel. Please notice the :members: and :undoc-members: directive options here. They are required in order to document all classes.

You've might come across a different issue here. If that's the case, please provide a minimal working example. The above code should at least work on your machine as it is (with sphinx 4.1.2 & pydantic 1.8.2), too. To ensure you have the correct version of autodoc_pydantic installed in your local doc build environment, just create a new env and pip install git+git://github.com/mansenfranzen/[email protected].

[StephenHogg]

My apologies, the problem I'm having appears to be because of the recursive autosummary thing.

[mansenfranzen]

No worries, now we know your issue is related to autosummary. Perhaps you could describe it in more detail in #33 if it provides any more insight.

[tahoward]

@mansenfranzen Thanks for looking into this I'll pull in dev release and see what output looks like.

[tahoward]

@mansenfranzen I seem to be unable to replicate the original issue on your v1.3.1 release when comparing against the v1.3.2-a.1 tag. I do see my Sphinx dep got bumped to 4.1.2 now. Locked it back to 4.1.1 but still unable to replicate my original issue. Are you still able to replicate with your v1.3.1 release?

[mansenfranzen]

@tahoward I can still reproduce the issue even with sphinx 4.1.2. The hyperlink does not show up in v1.3.1 but is present in v1.3.2-a.1. Either way it works for you 😉.

[tahoward]

@mansenfranzen Agreed!