Improve README

[obestwalter]

restart with a fresh addressing suggestions from previous PR

re-opening. Based on botched up #1079

see #819

preview: https://github.com/tox-dev/tox/tree/819-improve-readme

[obestwalter]

Looks like Github "sanitizes" all size hints: github/markup#295

That would be one argument for switching to markdown and simply using HTML for things like that. I'd really like the logo right aligned and smaller next to the First heading and with markdown that worked.

Alternative in rst would be to keep a scaled copy and use that here.

[gaborbernat]

I'm fine with switching to markdown, as long as works with both pypi and github 👍

[obestwalter]

size is sanitized but you can use the raw directive - which is obviously much safer 🤣

[gaborbernat]

Do you think raw will work on PyPi too?

[obestwalter]

If there are no glaring errors left, I think we can merge this now.

[obestwalter]

Do you think raw will work on PyPi too?

arg ... I don't know. Shall we try to find outor just switch to markdown? Thanks to pandoc it's no pain either way to switch formats.

[obestwalter]

A quick search suggests that it doesn't: https://stackoverflow.com/a/49107899/2626627

Question is if PyPI supports pure HTML coming from a markdown document either - I'll try it out on the test instance.

Stack Overflow

README.rst fails to render on PyPi

I have a README.rst in my project hosted on GitHub. It renders fine on GitHub but fails to render on PyPi i.e. I see raw content on the PyPi project description page.

I have looked through similar

[obestwalter]

raw directive is not supported for rst (readme-renderer also flags that).

$ twine check dist/*

[...]
The project's long_description has invalid markup which will not be rendered on PyPI. The following syntax errors were detected:
line 4: Warning: "raw" directive disabled.
Checking distribution dist/tox-0.9.1.tar.gz: Failed
The project's long_description has invalid markup which will not be rendered on PyPI. The following syntax errors were detected:
line 4: Warning: "raw" directive disabled.
line 4: Warning: "raw" directive disabled.

[obestwalter]

It does work with markdown though 🍾

$ twine check dist/*

Checking distribution dist/tox-0.9.2-py2.py3-none-any.whl: Passed
Checking distribution dist/tox-0.9.2.tar.gz: Passed

[obestwalter]

o.k. I think markdown it is then and I'll update the release / check bit also now.

[gaborbernat]

The CI still fails... 🤔

[obestwalter]

Are we not checking the README with readme-renderer anymore? Can't find it, but might be packaged differently now.

[gaborbernat]

readme-renderer is now part of twine 👍 because of PEP-517. see pypa/twine#395

in the meantime just add it to the package readme tox deps section alongside twine the md extras

[obestwalter]

2019-01-02T14:28:36.5844635Z package_description runtests: commands[1] | twine check '/home/vsts/work/1/s/.tox/package_description/tmp/build/*'
2019-01-02T14:28:37.0299156Z /home/vsts/work/1/s/.tox/package_description/lib/python3.7/site-packages/readme_renderer/markdown.py:38: UserWarning: Markdown renderers are not available. Install 'readme_render[md]' to enable Markdown rendering.
2019-01-02T14:28:37.0299940Z   warnings.warn(_EXTRA_WARNING)
2019-01-02T14:28:37.0300451Z Checking distribution /home/vsts/work/1/s/.tox/package_description/tmp/build/tox-3.6.2.dev13+g4e56ae3-py2.py3-none-any.whl: Failed
2019-01-02T14:28:37.0300991Z The project's long_description has invalid markup which will not be rendered on PyPI. The following syntax errors were detected:
2019-01-02T14:28:37.0301214Z line 4: Warning: "raw" directive disabled.

It's happening, but I haven't figured out yet where. Haven't looked at how we do stuff now yet, so will check.readme-renderer need top be installed with [md] for it to work.

[obestwalter]

readme-renderer is now part of twine +1 because of PEP-517.

cool but maybe without markdown check? I tried locally and still needed it pip install the md stuff.

[obestwalter]

yep, that's the reason. Will check if there is an issue about this already. I guess we are not the only ones who want to do this and run into it.

[gaborbernat]

https://github.com/pypa/twine/blob/master/setup.py#L84 could be a twine bug 👍 they probably should forward the extras 👍

GitHub

pypa/twine

Utilities for interacting with PyPI. Contribute to pypa/twine development by creating an account on GitHub.

[obestwalter]

I just read a bit about it and am a bit confused about the state of markdown in readme-renderer, as apparently it can never fail, so this could mean its never checked but only fails when md extras are not installed. I'll add a dep in our tox env to install it extra but will get in touch with PyPA about how to solve this generally.

pypa/twine#421

[todo]

installing readme-renderer[md] should not be necessary

tox/tox.ini

Lines 44 to 48 in 7f88569

	# TODO installing readme-renderer[md] should not be necessary
	readme-renderer[md] >= 24.0
	pip >= 18.0.0
	skip_install = true
	extras =

---

This comment was generated by todo based on a TODO comment in 7f88569 in #1114. cc @tox-dev.

[obestwalter]

I asked about it on the list. If there is consensus about making markdown support the default it could be "fixed" in readme-renderer diretly by adding the dependency to the normal install_requires deps and everything else can go away: https://groups.google.com/forum/#!topic/pypa-dev/BevObZsKVOQ

Google Groups

Google Groups allows you to create and participate in online forums and email-based groups with a rich experience for community conversations.