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

update Sphinx config #160

Closed

Conversation

terencehonles
Copy link
Contributor

@terencehonles terencehonles commented Nov 15, 2021

Pulling changes out of #144

Fixes this:

Screenshot from 2021-11-15 10-47-43

To this:

Screenshot from 2021-11-15 11-01-54

If you're using Sphinx > 4.1 you can use autodoc_typehints as both instead of description as I had initially put in #144 and you put in ed0d3cc, if not you should leave description since both is not understood and will become signature.

The autoclass_content = "both" does not actually seem like it's needed either anymore or maybe at all, but it's something I've run into before and is confusing that that isn't the default behavior. It will concatenate any docstring in __init__ and in the class body in order to document the class. There doesn't seem to be any documentation in the __init__ so it's unneeded, but it doesn't hurt to have so you don't have potentially future documentation get ignored.

See:

source_suffix = [".rst", ".md"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
pygments_style = "sphinx"
autodoc_typehints = "description"
autoclass_content = "both"
autodoc_typehints = "both"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just calling out so it doesn't get burried in the PR description, this requires Sphinx 4.1 and probably shouldn't be changed on older versions.

@kislyuk
Copy link
Owner

kislyuk commented Nov 29, 2021

This change does not appear to be necessary. I prefer to put type hints in the description, not signature, to keep the signature more readable. And with the current configuration, sphinx already renders the type hints in the parameter description correctly (see https://kislyuk.github.io/watchtower/#watchtower.CloudWatchLogHandler).

@terencehonles terencehonles deleted the update-sphinx-config branch November 29, 2021 18:12
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.

2 participants