PyPI documentation not rendered properly

[matthewfeickert]

Description

Currently (pyhf v0.0.16) the docs on PyPI are not being rendered correctly. This shouldn't be the case as

$ python setup.py sdist
$ python setup.py bdist_wheel --universal
$ twine check dist/*
Checking distribution dist/pyhf-0.0.16-py2.py3-none-any.whl: Passed
Checking distribution dist/pyhf-0.0.16.tar.gz: Passed

for

$ pip freeze | grep 'twine\|readme-renderer'
readme-renderer==24.0
twine==1.13.0

If there was a problem with the rendering then twine check dist/* should have picked it up. Yet, it is being rendered wrong.

@lukasheinrich Can you tell us what versions of twine you're using when you run

twine upload dist/*

? I think there may have been an issue with twine v1.12.0 that got fixed recently in v1.13.0

Checklist

• Run git fetch to get the most up to date version of master
• Searched through existing Issues to confirm this is not a duplicate issue
• Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue

[webknjaz]

I strongly recommend you using pyproject.toml and building dists using pep517.build via a standardized interface :)

[matthewfeickert]

One of the things that is missing for PyPI is the following in MANIFEST.in

include docs/_static/img/*.png

[matthewfeickert]

I strongly recommend you using pyproject.toml and building dists using pep517.build via a standardized interface

@webknjaz I agree with you. I need to get around to implementing Issue #399

[matthewfeickert]

Ah, this is tricky. As is described here

PyPI does not support rendering from the package path itself, as it is not an image host.

So that means that we need to include links with targets of a hosted image on GitHub, e.g. the git diff would be

-<img src="docs/_static/img/manual_2_bin_100.0_145.0_100.0_150.0_15.0_20.0_30.0_45.0.png" alt="manual" width="500"/>
+<img src="https://raw.githubusercontent.com/diana-hep/pyhf/master/docs/_static/img/manual_2_bin_100.0_145.0_100.0_150.0_15.0_20.0_30.0_45.0.png" alt="manual" width="500"/>