Documentation problems ledger and additions

Note: pylint may have stuff to diagnose stuff missing in docstrings. Have a look there before looking elsewhere.

Pylint reference

Pylint features

Main problems

This is a place to collect observations on mistakes us humans make when writing docs.

This is to serve as a guide to those janitors that might need to clean up docs, but also, hopefully, for use to find or write tools to diagnose (and possibly repair) these kinds of problems.

• md single backquote instead of the correct rst double backquote, when quoting code objects
• md triple backquotes instead of the correct rst .. code-block ::
• Not skipping a line before a doctest block
• Not skipping a line after a doctest block
• copyright: it says ©NO COPYRIGHT, also needs the date of generation
• Missing argument or return description (perhaps better have nothing than an empty "Return-" or arg name without description?

Nice to haves

• include bi-directional from and to doc and GitHub pages (minimal readme is already included in cfg file)
• regenerate: how to do it? manually removing docs?
• inject external content: for example readme.md in the root