Convert the README.rst to .md to prettify the dockerhub display

[machawk1]

https://hub.docker.com/r/oduwsdl/ipwb/

...shows the symbols used for linking and formatting in https://github.com/oduwsdl/ipwb/blob/master/README.rst. RST was originally used for display in pypi. Pypi has since had a UI overhaul. Is the markdown support any better? If so, we might try to move to MD for the sake of readability in dockerhub. Alternatively, we might look to finding a way to ensure the README does not contain the meta content and still use the README.rst.

[ibnesayeed]

Looks like the proposal to support Markdown in PyPi is finally implemented.

https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi

[machawk1]

@ibnesayeed The README has been updated to MD and displays fine in GitHub and PyPi. Dockerhub seems to choke, however. Can you figure out what, if anything, Dockerhub requires differently than GitHub and PyPi in its MD?

[ibnesayeed]

GH is more versatile in parsing different common documentation formats, but DH is more limited to a more strict MD format. That's why current mixed up MD file is not rendering there properly, especially the way code blocks are annotated. If you want to take care of these then go ahead otherwise let me know and I will try to fix them and push a commit.

[machawk1]

Does an interface exist where I can test how MD will be rendered on Dockerhub?

Go ahead and try to fix them if you can without changing the visual display of the GitHub/PyPi document. If that's not possible (i.e., DockerHub MD restriction prevents some GH-MD feature), let me know.

[ibnesayeed]

No, I don't think they have a preview option, but I am sure I can fix it. I will work on this and push changes to the issue-399 branch. If those changes don't work well, then we can revert them.

[machawk1]

@ibnesayeed I recall you mentioning display issues with the README on DockerHub within some other repo. Can you link it here? The line breaking on the DockerHub version of the ipwb README contains odd line breaking, mis-aligned consecutive code blocks, etc.

[ibnesayeed]

Line breaking in the DH rendering is a long-known issue docker/hub-feedback#124. If we want to fix that now and make it consistent across all three places, we can just remove all the newlines from the MD source where they are not needed.

I have reported the misaligned consecutive code lines issue docker/hub-feedback#988 (comment).

[machawk1]

@ibnesayeed I was wondering what you meant by the first statement, checked out the README.md and noticed superfluous line breaks to a line width (maybe 80-chars?). This may have been the result of the RST->MD conversion script, as I am not prone to manually applying this sort of line breaking to free-form text (code is a different story).

[ibnesayeed]

Oh, I didn't know you used a conversion script. I am sure the fixed width text is a result of that. I did not change that, because I thought you did it intentionally. I can go ahead and make that change now.

[machawk1]

@ibnesayeed Do you think we can close this ticket or is more adjustment needed?

[ibnesayeed]

There is one little thing that I will fix and close this.

[machawk1]

Oh, right, is it the extra CRLF?

[ibnesayeed]

Oh, right, is it the extra CRLF?

Yes!

This should be sorted out by the #438 PR.