Link to documentation

[septatrix]

It was rather surprising for me when I noticed that this package actually has docs on readthedocs.
I only looked at the repository sidebar, in the readme and the pypi page.
Therefore it would seem beneficial to add a link to the documentation in the readme and potentially also in the pypi page (https://packaging.python.org/guides/distributing-packages-using-setuptools/#project-urls)

[jaraco]

It is linked from the README (and thus from PyPI also), but it's subtle:

I'm slightly reluctant to add more links because it would require more customization of this project (and by extension, any other project I maintain with RTD). I'd like any packaging technique to first apply to jaraco/skeleton and then derived here. So imagine for a moment the implications of making the change there. You might even consider submitting a PR there.

In fact, I'm going to move this issue there while I let you ponder the above.

[septatrix]

One thing which is often done and would not be covered by this code skeleton is link in the github sidebar which is where I for one look first.

The badge I did not notice as they are often overused and carry little meaning while adding a lot of visual noise - also the "passing" makes it seem like it relates to some CI job (which I guess is true because it presumably refers to RTD's own CI). However I can understand why one would not want to add an extra section to the readme just for an extra link. Apart from that there is also the possibility to add a link inside of the PyPi metadata which seems like a good place. Maybe I will make a PR for that.

[jaraco]

In pypa/setuptools#2892, @hugovk also requested more visibility of documentation. Here's what I proposed:

I'd like to see something like:

• A routine that detects RTD is enabled by parsing the README and extracts the URL.
• A plugin for setuptools that adds a Documentation Project-URL if that badge is enabled.
• A routine in jaraco.develop that adds a link to the changelog if a documentation URL is available in the metadata.

If this functionality were added, it would rely on the existing signals to generate the metadata in useful places.

[septatrix]

I see several problems with the proposed solution regarding the made assumptions about the project. The skeleton is made very universal however this also means that there will be people using this skeleton which are not using RTD, setuptools or jaraco.develop. This will not always be the case. Also dynamically extracting some data from e.g. README comes with some complications and edge-cases like different formatting or people switching from rtf to markdown...

[jaraco]

The reason I'd like to extract the information from the readme is that (a) that's currently the sole place that advertises the presence of published docs (and their location) and (b) it's not readily possible for the readme to derive from other sources. The moment you create two places to configure the docs, you introduce the possibility for them to be out of sync and so create a dependency and maintenance burden between those two or more places.

In practice, I'd like there to be a single place not in the readme that declares the presence of docs, but due to the static nature of README rendering, that may not be possible. Even better would be not to require configuration at all (auto-detect the presence of docs).

I'd be open to removing the docs badge from the README, especially if that means that users have a clearer path to the documentation.

I'm also open to other proposals, as long as they keep the configuration burden small.

[dalito]

Could you update the link in the github sidebar of this repository to point to the new blog entry https://blog.jaraco.com/skeleton/ ?

[jaraco]

Could you update the link in the github sidebar of this repository to point to the new blog entry https://blog.jaraco.com/skeleton/ ?

Done.