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 1 commit into from Mar 27, 2019


Copy link

@Gallaecio Gallaecio commented Mar 25, 2019

…API members

Copy link

@codecov 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
Copy link

@kmike kmike Mar 26, 2019


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

@Gallaecio Gallaecio Mar 27, 2019

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

Copy link

@kmike kmike Mar 27, 2019

Looks perfect to me, thanks @Gallaecio!

@Gallaecio Gallaecio force-pushed the documentation-policy-api branch from e0dc5bd to ce837b0 Mar 27, 2019
@kmike kmike merged commit 820adb6 into scrapy:master Mar 27, 2019
3 checks passed
@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
None yet
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants