Make the package README look good for pypi landing page

[stscijgbot-jp]

Issue JP-1865 was created on JIRA by James Davies:

Currently the PyPI landing page for the jwst package is sparse.

https://pypi.org/project/jwst/

This is because long_description in setup.cfg is minimal.

https://github.com/spacetelescope/jwst/blob/569435370083047ca9952e2c03b617534abfefbb/setup.cfg#L4-L5

Ideally it would contain much of the contents of README.md with a short introduction, installation, basic usage and some snappy graphics. This is easily done in setup.cfg as

long_description = file: README.md
long_description_content_type = text/markdown

But we may want to split up the README into general purpose for PyPI and specific for internal installations, DMS, etc. If using rst instead of markdown, one can do this. I.e.

long_description = file: README_pypi.rst
long_description_content_type = text/x-rst

and have the main README.rst include README_pypi.rst. Or even

long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
long_description_content_type = text/x-rst

So we may want to switch to a README.rst to allow this. We have options.

[jdavies-st]

After a discussion with @hbushouse, for PyPI it looks like we should use the following sections for the README:

• Installation (only the basic pip install parts)
• CRDS setup
• Contributions and Feedback

@nden should we completely remove the https://github.com/spacetelescope/jwst#jupyterhub-access section? From what I can tell, that doesn't even work anymore.

[jdavies-st]

So it turns out that breaking up the README and only using parts of it for PyPI and using .. include::file.rst doesn't work, as one would need to pre-process these files using sphinx or pandoc to get the includes to show up. So this is a non-starter.

I think the best way to do this, and also to solve the problem of our much-too-long README and having a table of contents is to make the README a simple table of contents with links to the relevant information elsewhere (usually the docs). This would solve the problem of keeping our installation instructions in the README synced with the installation instructions in the docs. I like how it is done here in this repo:

https://github.com/pypa/virtualenv

They also include their changelog in their docs as well, which is very nice.

Thoughts?

[nden]

The table format will work. Instead of a link to the Changelog a link to the current release notes (https://github.com/spacetelescope/jwst/releases/) would normally show the changelog and other information - usually we summarize important changes in the final build release. Also, since this is the landing page on github, should we include also a link to JDocs and a sentence about JWST, e.g. straight from the NASA page, The James Webb Space Telescope (JWST) is an orbiting infrared observatory that will complement and extend the discoveries of the Hubble Space Telescope, with longer wavelength coverage and greatly improved sensitivity.

[hbushouse]

Withdrawn by author.

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Withdrawn by author