search

pypa / readme_renderer

Safely render long_description/README files in Warehouse
Apache License 2.0
157 stars 88 forks source link

Include docinfo when rendering rst #99

Closed theacodes closed 6 years ago

theacodes commented 6 years ago

Closes #61.

Screenshot of docinfo on Warehouse:

screen shot 2018-04-20 at 10 47 51 am

di commented 6 years ago

Would it make sense to put the docinfo at the end of the rendered description, rather than at the beginning?

theacodes commented 6 years ago

Possibly, but we'd be breaking precedence with literally every other rst renderer (docutils, sphinx, and github).

di commented 6 years ago

Well, we already are by only rendering the fragment. My concern is that most users reading a projects description probably want to read the first couple lines of the description, not all this metadata. We've already gotten some complaints that there is not enough information density on small screens, and I think this might aggravate it.

I think it might also be unclear to users that this metadata is coming from the description, and not from PyPI itself. For example, in your screenshot, the date of the "created" line is pretty much always going to disagree with the release date. At least in this example, a lot of this information (license, author, project name) is already going to be included in the sidebar on PyPI anyways as well.

I'd like to hear what others (@dstufft, @ewdurbin) think.

theacodes commented 6 years ago

Totally fair points. Definitely interested to see what others say.

theacodes commented 6 years ago

After discussing with @dstufft and @di in person, we decided to merge this as-is. Although this isn't pretty, we don't want to deviate from how GitHub renders things. Additionally, this is optional and present on a fairly small number of readmes.