A problem with big struct

[ozzyst]

Hello! I have some struct if I try to create doc I have warning

:1: WARNING: undefined label: #/definitions/inner_struct (if the link has no caption the label must precede a section header)

I have this error on all inner structs. Do you have any ideas?

My rest look like as this

....
.. pydantic:: module.UpperStruct
.. pydantic:: module.InnerStruct in UpperStruct
.. pydantic:: module.InnerInnerStruct in InnerStruct

And my struct:

InnerInnerStruct(BaseModel):
    inner_inner_inner: Any

InnerStruct(BaseModel):
    inner_inner: InnerInnerStruct

UpperStruct(BaseModel):
    inner: InnerStruct

[Zsailer]

Your example is a bit confusing to me. What is your precise syntax?

i.e. is it actually .. pydantic:: module.InnerInnerStruct in InnerStruct, and if so, what do you expect to get from this syntax?

[ozzyst]

I think I confused you, sorry. I will try to rewrite my issue.

Sample struct:

class InnerStruct(BaseModel):
    first: str
    second: bool
    third: int


class Struct(BaseModel):
    data: Optional[List[InnerStruct]]

my .rst file

.. pydantic:: papi.models.overview.Struct
.. pydantic:: papi.models.overview.InnerStruct

When I use make html I have got this warning:
<unknown>:1: WARNING: undefined label: #/definitions/innerstruct (if the link has no caption the label must precede a section header)

Docs are ready, but link to the inner struct is not available.

[Zsailer]

Thanks, @ozzyst. That's really helpful. 😄

It looks like pydantic-sphinx can't parse custom types that generated by Pydantic objects. I'll need to do a deeper dive into this when I get time.

For reference, the JSON that's returned by Struct.schema_json() looks like this:

{
  "title": "Struct",
  "type": "object",
  "properties": {
    "data": {
      "title": "Data",
      "type": "array",
      "items": {
        "$ref": "#/definitions/InnerStruct"
      }
    }
  },
  "definitions": {
    "InnerStruct": {
      "title": "InnerStruct",
      "type": "object",
      "properties": {
        "first": {
          "title": "First",
          "type": "string"
        },
        "second": {
          "title": "Second",
          "type": "boolean"
        },
        "third": {
          "title": "Third",
          "type": "integer"
        }
      },
      "required": [
        "first",
        "second",
        "third"
      ]
    }
  }
}

Looks like sphinx-pydantic will need to provide a way to handle JSON objects with reference to "outside" JSON schemas/ Pydantic objects. It will have to parse the "#/definitions/InnerStruct" line and develop an internal link to that object's documentation.

If you'd be interested in exploring this further and submitting a PR, that would be awesome! I'm a bit short on time right now, so I likely can't work on this for the next couple of weeks.

[ozzyst]

Thank you so much for your answer! If I can to fix it I will create PR

[danieljmv01]

Hi! I had the same issue and I want to share the workaround that I am using, in case someone finds it useful.

Adding the reference to the label of the warning suppressed the warning and created a link to the pydantic's sub-model instead of the #/definitions/... string.

I am not allowed to share anything from my project, but I think that the @ozzyst's second example should work if the .rst is modified as follows:

. . pydantic:: papi.models.overview.Struct
.. _#/definitions/innerstruct:
.. pydantic:: papi.models.overview.InnerStruct

[ibackus]

I love this package! I just started using it, and I am also having the same issue.

[chetanfegade]

I was able to resolve this with the workaround suggested by @danieljmv01 . Thanks :-)