Fix Markdown formatting issues after conversion from RST

[ibnesayeed]

Mainly fixed language annotations in code blocks as noted in #399.

[codecov]

Codecov Report

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

@@           Coverage Diff           @@
##           master     #422   +/-   ##
=======================================
  Coverage   23.29%   23.29%           
=======================================
  Files           6        6           
  Lines        1112     1112           
  Branches      169      169           
=======================================
  Hits          259      259           
  Misses        836      836           
  Partials       17       17

---

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 45f8938...b8e6465. Read the comment docs.

[machawk1]

LGTM! I am not a big fan of the underline in the sections as added when we promote the headings per your edits but it results in more structured markup (H2 instead of H3), so I suppose I will relent fighting GH's MD->HTML/CSS style.

[ibnesayeed]

That change was made mainly due to semantic reasons, not stylistic. I had no problem with them being H3, but there was no H2 in the hierarchy.

I have noted two issues, 1) DH breaks lines in rendering when there is a line break in the source (docker/hub-feedback#320 (comment)) and PyPi eats up leading zeros from the hour-minute combo (e.g., 0439 becomes 439).

[machawk1]

I have been aware of the latter (PyPi versioning) issue since we started pushing it there and encountered a date with a leading 0. The leading 0 keeps lexical positioning sorting, so I have retained using that style despite PyPi's behavior.

[ibnesayeed]

PyPi should take version number as opaque string though.

[machawk1]

I completely agree though maybe they do it on the PEP-440 rationale:

All numeric components MUST be interpreted and ordered according to their numeric value, not as text strings.

[machawk1]

On the contrary, same PEP:

All release segments involved in the comparison MUST be converted to a consistent length by padding shorter segments with zeros as needed.

[ibnesayeed]

I came to know the reasoning behind this because they wanted to ensure 00 == 0 in version numbers as per pypa/setuptools#302 (comment).