Linking to documentation from the README

[Lucia-Fonseca]

Describe the bug
The link for the Contributor Guidelines in the README.rst is broken.

To Reproduce
Steps to reproduce the behavior:

1. Go to README.rst
2. Click on 'Contributor Guidelines' under the "Contributing" section.
3. See error
   Sorry. This page does not exist yet

Expected behavior
The link should lead you to our Contributing Guidelines in the stable documentation.

Desktop (please complete the following information):

• OS: macOS
• Version 11

[rrjbca]

Before we make any changes can we discuss more generally wether we want to use hyperlinks to "stable" or "latest" documentation builds throughout the project? PR #416 is already open trying to change some links to "stable" while this issue is proposing the opposite. I think there is a fundamental question about wether the README and docs form part of a release, in which case they should surely use the appropriate "stable" links to remain self-consistent? And shouldn't we be thinking of the main branch as "unstable" and hence "latest" only exists for the benefit of developers working towards a new release?

[Lucia-Fonseca]

Oh sorry I didn't see that. I was going through the list of issues and saw nothing.

[Lucia-Fonseca]

However, despite the discussion whether we want to use "stable" or "latest", PR #449 is to fix that the link is broken. I am using the stable version as you propose in #416.
If you think this issue and #449 overlaps with #416, please feel free to close them.

[ntessore]

README on main branch should link docs for main branch, i.e. latest. Docs for releases, e.g. on the PyPI page, should like to docs for that release, i.e. tagged.

We could easily write a script that automates packaging by patching the README before a release to PyPI. We could similarly add a project_urls = entry to our setup.cfg that links the correct docs in the PyPI side bar.

Edit: As we are passing into stable territory, we should in any case make the PyPI links for informative: Replace the broken skypy.info link for our homepage with a link to the docs, and add project_urls for repository, issues etc.

[rrjbca]

However, despite the discussion whether we want to use "stable" or "latest", PR #449 is to fix that the link is broken. I am using the stable version as you propose in #416.
If you think this issue and #449 overlaps with #416, please feel free to close them.

No, the link is currently dead because the page name has changed from upper to lower case since the last release and so the new name didn't exist at the time "stable" was last built. Without any change this will "fix-itself" with the next release. Your proposed change is simply linking to the old stable page and will break again after the next release as the upper case page name no longer exists on main.

[rrjbca]

README on main branch should link docs for main branch, i.e. latest. Docs for releases, e.g. on the PyPI page, should like to docs for that release, i.e. tagged.

I would agree in principle, except most users treat repository READMEs on github like the "front page" for the project without appreciating that it could live on a branch that is under development. As such I'm really hesitant to put links to documentation for code that is unreleased and/or under development on the readme.

We could easily write a script that automates packaging by patching the README before a release to PyPI. We could similarly add a project_urls = entry to our setup.cfg that links the correct docs in the PyPI side bar.

Yep this is a good idea to ensure that the releases are self-consistent

[ntessore]

I would agree in principle, except most users treat repository READMEs on github like the "front page" for the project without appreciating that it could live on a branch that is under development. As such I'm really hesitant to put links to documentation for code that is unreleased and/or under development on the readme.

Do you have anything to indicate that the average user of Astropy or SciPy ever looks at astropy/astropy or scipy/scipy at all? I would think that once we have properly set up web and documentation pages, the only people making it to the repository will be people looking for the code. Everyone else will either follow the link on the arXiv page (-> website), google the name (-> website), or go through the PyPi page (-> website).

[rrjbca]

You are right that probably most users don't ever visit the repo page, but clearly some do stumble upon it. I like the idea of separating the website for users and the repo for developers. That helps indicate what sort of information should be in the readme on main. The obvious requirement being that we need a website.