Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use only autodoc to generate the API documentation #1021

Merged
merged 9 commits into from Dec 2, 2022

Conversation

DanielNoord
Copy link
Contributor

@DanielNoord DanielNoord commented Nov 28, 2022

As discussed in #1019 autoapi has some issues with typing annotations.

This creates almost parity with the current documentation. There are slight differences in lay-out and some additional classes get documented (they could be excluded by hand).
I tested this with the other PR and could build with make html without any validation errors. I'll rebase that PR on this one as a final test.


📚 Documentation preview 📚: https://python-jsonschema--1021.org.readthedocs.build/en/1021/

@codecov-commenter
Copy link

codecov-commenter commented Nov 28, 2022

Codecov Report

Base: 98.21% // Head: 98.21% // Increases project coverage by +0.00% 🎉

Coverage data is based on head (8304e41) compared to base (2815178).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1021   +/-   ##
=======================================
  Coverage   98.21%   98.21%           
=======================================
  Files          20       20           
  Lines        3529     3530    +1     
  Branches      537      537           
=======================================
+ Hits         3466     3467    +1     
  Misses         47       47           
  Partials       16       16           
Impacted Files Coverage Δ
jsonschema/_format.py 94.39% <ø> (ø)
jsonschema/exceptions.py 98.14% <100.00%> (+0.01%) ⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

@DanielNoord
Copy link
Contributor Author

I really have no idea how to fix this anymore. autodoc just seems unable to pick up TypeVars or aliases from imported modules. The documentation of a class from a private module in the index of the API reference (FormatChecker from _format) which uses a private alias from the module (_F) seems to completely throw off Sphinx and autodoc. I have searched online but wasn't able to find much help as to how this could be fixed...

As far as I can see now, I don't think any additional typing can be included into the documentation without completely restructuring it.

@Julian
Copy link
Member

Julian commented Nov 29, 2022

I can try to have a look in a bit, thanks for the efforts so far.

* origin/main:
  Remove noise from the Sphinx config.
  Fix instantiating validators with cached refs-to-bool schemas.
  Try fixing more Sphinx refs which fail only on Ubuntu...
@Julian
Copy link
Member

Julian commented Nov 30, 2022

OK, the commit I just pushed I believe should move this forward.

@DanielNoord
Copy link
Contributor Author

@Julian This looks perfect! Well done figuring this out, I wasn't able to...

I'm fine with merging!

@Julian Julian merged commit e24f0ee into python-jsonschema:main Dec 2, 2022
@DanielNoord DanielNoord deleted the docs/autodoc branch December 2, 2022 20:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants