refactor README to markdown and update badging

[prjemian]

The repo's README can be refactored to markdown. The badging needs an update as well, since various tools have been swapped.

[prjemian]

Should not have been closed in #145.

[prjemian]

@carterbox - This is easy. But the docs include the README.rst directly. A new page should be created in the docs separate from the refactored README.md.

[carterbox]

Why do you want to duplicate your docs? What's the problem with using the RST for both README and docs landing page?

[prjemian]

The project README file has similar but slightly different purposes than similar content int he documentation.

Here's why I am tending to separate these now. As in other projects, it becomes cumbersome to continue rendering some content (such as badges) in the documentation. With badges, they are often updated after the online docs have been recreated. Continuing to use the project README in the published documentation limits the formatting options for both the project README and the published documentation.

[carterbox]

My understanding is that you don't want broken badges on your archived (non-latest/stable) version of the docs, so you have separated the landing pages and only have badges only on the GitHub landing. Makes sense.

But what changes besides removing the Depsy badge (the only broken badge) do you want to this landing page? Removing the Depsy badge does not require swapping from RST to MD. There should be a something else that you want which is enabled by switching to MD?

[prjemian]

(such as badges)

which means that other maintenance becomes easier. It has become tiresome trying to make this page work both in the documentation (as .rst) and as the project description page in the GitHub repository. It is not necessary to make these two use cases render the exact same information.

[prjemian]

Wait for PR #154 to be merged before proceeding, other wise a merge conflict will exist.

[prjemian]

(bluesky_2022_1) prjemian@zap:~/.../prjemian/punx$ git grep README
MANIFEST.in:include README.rst
setup.cfg:description-file = README.rst
setup.py:README = os.path.join(os.path.dirname(__file__), "README.rst")
setup.py:long_description = open(README, "r").read()

[prjemian]

So, the README is not currently used in the documentation.

[prjemian]

The long_description appears on PyPI, for example. In the pvview project, the README is markdown:

long_description = open('README.md', 'r').read()

but the PyPI page displays the markup and this looks like an error.

[prjemian]

README page is still not very pretty but it is a direct translation (via pandoc).