Improve documentation

[multani]

Changes

• Add cross-reference links in many, many places
• Improve the rendering of the documentation in many places
• Fix a bunch of typos and doc compilation warnings
• Improve build system: more recent packages, removed unused packages,
  doc warnings are now errors

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes
• Add a new news fragment into the CHANGES folder
  • name it <issue_id>.<type> (e.g. 588.bugfix)
  • if you don't have an issue_id change it to the pr id after creating the PR
  • ensure type is one of the following:
    • .feature: Signifying a new feature.
    • .bugfix: Signifying a bug fix.
    • .doc: Signifying a documentation improvement.
    • .removal: Signifying a deprecation or removal of public API.
    • .misc: A ticket has been closed, but it is not of interest to users.
  • Make sure to use full sentences with correct case and punctuation, for example: Fix issue with non-ascii contents in doctest text files.

Improvements

Some examples:

SSL Authentication

Before:

After:

Consumer API

Before:

After:

[codecov]

Codecov Report

Merging #722 (a828a55) into master (d3fa429) will increase coverage by 0.00%.
The diff coverage is 100.00%.

❗ Current head a828a55 differs from pull request most recent head 36d6e47. Consider uploading reports for the commit 36d6e47 to get more accurate results

@@           Coverage Diff            @@
##           master     #722    +/-   ##
========================================
  Coverage   97.87%   97.87%            
========================================
  Files          29       31     +2     
  Lines        5218     5360   +142     
========================================
+ Hits         5107     5246   +139     
- Misses        111      114     +3     

Flag	Coverage Δ
cext	88.56% <100.00%> (+0.29%)	⬆️
integration	97.83% <100.00%> (+<0.01%)	⬆️
purepy	97.40% <100.00%> (+0.01%)	⬆️
unit	52.10% <100.00%> (+1.37%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
aiokafka/abc.py	72.22% <ø> (ø)
aiokafka/consumer/consumer.py	97.91% <ø> (ø)
aiokafka/errors.py	100.00% <ø> (ø)
aiokafka/helpers.py	100.00% <ø> (ø)
aiokafka/producer/producer.py	98.53% <ø> (ø)
aiokafka/structs.py	100.00% <100.00%> (ø)
aiokafka/util.py	97.95% <0.00%> (-0.12%)	⬇️
aiokafka/conn.py	93.61% <0.00%> (-0.06%)	⬇️
aiokafka/client.py	98.15% <0.00%> (-0.02%)	⬇️
aiokafka/producer/sender.py	98.68% <0.00%> (ø)
... and 3 more

---

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 d3fa429...36d6e47. Read the comment docs.

[tvoinarovskyi]

Thank you very much for your contribution! Looks really good!