Styling lost with Jupyter Book

[mansenfranzen]

Styling lost with Jupyter Book

[mansenfranzen]

Hi @StigKorsnes,

sorry for letting you wait - I was busy otherwise.

Your issue seems to be related to how custom autodoc extensions automatically provide a new css class with the same name as objtype/directivetype. Without autodoc_pydantic, documenting python classes get the css class named class. Here is an extraction of the generated autodoc HTML source code without using autodoc_pydantic:

<dl class="py class">

When enabling autodoc_pydantic, the above HTML changes to:

<dl class="py pydantic_model">

As far as I know there is no easy way to change this behavior. It would be best to have both classes available like:

<dl class="py class pydantic_model">

The same holds for pydantic fields, settings and so on:

• pydantic_model -> class
• pydantic_settings -> class
• pydantic_field -> attribute
• pydantic_validator -> method
• pydantic_config -> class

Hence, the issue lies in replacing css class class with pydantic_model.

How this affects your theming is dependent on whether your theme makes use of the original css classes (class, attribute, method) or not. For example, the standard read-the-docs theme has no issue with it. However, your theme obviously makes use of it.

One hackish work around is to simply add all styles that are given under class, attribute, method to the corresponding autodoc_pydantic css classes as show above. This should work.

It would be great if you could test this approach. If it works, it would be worth adding it to the users FAQ section as long as I can't provide a proper fix codewise.

[StigKorsnes]

Hi @mansenfranzen
Thank you very much for your response. I quickly realized that this issue had nothing to do with your package, as I encountered the same issue with sphinx-toolbox and enum_tools. (for named tuples and enums, which also lacks a bit out-of-the-box).

My experience and understanding of CSS is close to zero, so do not know how to go about to fix the build-step of my documentation. However, I was able to open the dev tools and throw a "class" in there to witness magic happen :) (py class pydantic_model). I guess I will have "up" my skillset in order to implement any sort of hack. Had a colleague test it out with RTD and sphinx, where everything looks nice, as you have already mentioned.

Jupyter-book uses a custom book-theme, and I guess since this and other contributed extensions work in other themes, that the issue lies here. Posted an issue here. Since this issue applies not only to your package, but all other contributed extensions with similar goals, I think it does deserve a bit more attention than currently given. (0 replies). Feel free to post a short comment, any support is appreciated.

Thank you very much for your reply!

[mansenfranzen]

@StigKorsnes Thanks for the response - I'm glad it seemed to have helped you. Just to clarify so I don't misunderstand you: When you add class then the styling is correct again?

More importantly, your issue gave me the idea to use sphinx events to add the missing css class class automatically. This will be in fact a useful addition to the package and perhaps for other packages, too.

I will let you know about the new feature in the next release.

[mansenfranzen]

@all-contributors please add @StigKorsnes for bug and ideas

[allcontributors]

@mansenfranzen

I've put up a pull request to add @StigKorsnes! 🎉

[mansenfranzen]

The current release v1.6.0 adds the relevant fallback classes by default. Therefore, the newest version of autodoc_pydantic should work fine with jupyter-book theme out of the box, now. It would be great, if you could test this once again to confirm that I'm not mistaken.

There is a new FAQ section in the updated documentation describing your issue.

Feel free to reopen or comment. Thanks once again for reporting the issue.

[StigKorsnes]

@mansenfranzen
Updated to 1.6.0, and everything looks good!

autodoc-pydantic 1.5.1 :

autodoc-pydantic 1.6.0 :

Thank you very much for this. The dl element now reads class="py class pydantic_class". Would you recomend your implemented solution to other packages such as sphinx-toolbox and enum_tools? I used sphinx toolbox to get better looking docs for namedtuples, and enum_tools for better looking enumerations. Both of them had the same issue with jupyter-book.

[mansenfranzen]

Thanks for the visual confirmation - looks good :-).

I believe that this feature is also relevant for other sphinx autodoc extensions. Thanks for linking this PR to the related packages.