Support for Python coroutines

[ovekaaven]

Subject: Add support for Python coroutines

This feature was proposed in #4777.

I've split the patch I proposed into 3 different changesets, and simplified the autodoc part by putting the async check into the common Documenter.add_directive_header instead of its subclasses, which may or may not be to your liking. I can go back to overriding add_directive_header in the subclasses if you prefer that, but I doubt it makes much practical difference.

[codecov]

Codecov Report

Merging #4847 into master will increase coverage by <.01%.
The diff coverage is 87.5%.

@@            Coverage Diff             @@
##           master    #4847      +/-   ##
==========================================
+ Coverage   82.15%   82.15%   +<.01%     
==========================================
  Files         289      289              
  Lines       38141    38157      +16     
  Branches     5915     5918       +3     
==========================================
+ Hits        31333    31347      +14     
- Misses       5488     5490       +2     
  Partials     1320     1320

Impacted Files	Coverage Δ
sphinx/domains/python.py	76.87% <0%> (-0.32%)	⬇️
sphinx/util/inspect.py	74.09% <100%> (+0.66%)	⬆️
sphinx/ext/autodoc/__init__.py	85.21% <100%> (+0.03%)	⬆️
sphinx/pycode/parser.py	95.73% <100%> (+0.01%)	⬆️
sphinx/__init__.py	57.5% <0%> (-2.5%)	⬇️
sphinx/builders/html.py	82.48% <0%> (+0.11%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1958596...f3591f3. Read the comment docs.

[tk0miya]

Sorry for very late reviewing.

LGTM with nits.
Could you add testcase for coroutines please?

[tk0miya]

ping. The feature freeze for Sphinx-1.8 comes soon (see #4986).
So please let me know status of this PR.

I really want to merge this into next release.

[tk0miya]

Fixed by #6295 instead.
Thank you for your contribution.