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 the documentation policies: Ask to use docstrings to document … #3701

Merged
merged 1 commit into from
Mar 27, 2019

Conversation

Gallaecio
Copy link
Member

…API members

@codecov
Copy link

codecov bot commented Mar 25, 2019

Codecov Report

Merging #3701 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #3701   +/-   ##
=======================================
  Coverage   84.72%   84.72%           
=======================================
  Files         168      168           
  Lines        9461     9461           
  Branches     1407     1407           
=======================================
  Hits         8016     8016           
  Misses       1188     1188           
  Partials      257      257

its sub-modules.
Use docstrings for documenting API members (classes, methods, etc.) and make
sure that the Sphinx documentation uses the autodoc_ extension to pull the
docstring.
Copy link
Member

Choose a reason for hiding this comment

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

👍

What do you think about making it a bit more nuanced? I think that's fine to have more lenghty tutorial-style docs in actual docs, even if they relate to a particular class. In this case only part of the docs may be pulled from docstrings. There shouldn't be duplication, and we should prefer docstrings, but we may use a mix of docs + docstrings when it makes sense. Are you ok with something like that? If yes, do you think we should mention this point explicitly?

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree, but I’m unsure how to word it. I’ve just made an attempt, let me know what you think.

Copy link
Member

Choose a reason for hiding this comment

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

Looks perfect to me, thanks @Gallaecio!

@Gallaecio Gallaecio force-pushed the documentation-policy-api branch from e0dc5bd to ce837b0 Compare March 27, 2019 06:09
@kmike kmike merged commit 820adb6 into scrapy:master Mar 27, 2019
@kmike kmike added this to the v1.7 milestone Mar 27, 2019
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