Re: [Distutils] Alternate long_description formats, server-side

[Nick Coghlan]

On 3 Jun 2016 4:03 am, "Donald Stufft"  wrote:
>
>
>> On Jun 2, 2016, at 9:16 PM, Nick Timkovich 
wrote:
>>
>> I can definitely believe there are more important things to do, but some
of us aren't versed in the intricacies of what's up top and don't have the
familiarity to dive in. Us GitHub plebs are just raring to work on a
feature we think is within our grasp ;-)
>>
>
> Yup! Nick was speaking to why folks like myself haven’t done it yet- If
some enterprising person (perhaps you!) takes the time to write up a PEP
and work it through the process, then there’s no reason to wait for me (or
Nick, or any of the other core team) to do it :)

Right, the key part of my post is the second paragraph: we actually now
have a relatively simple mechanism to capture proposals like this one,
which is issues and pull requests against the "specifications" section of
the Python packaging user guide on GitHub.

Previously a key sticking point was not having a way to document added
fields without a full PEP, which imposed way too much overhead for adding a
simple attribute like Provides-Extra or the Description-Format field being
considered here.

For this to work, I think the concrete changes you would need would be:

- Python packaging user guide to document the new field in the core
metadata spec
- setuptools to support setting it
- Warehouse to respect it for all defined rendering formats
- potentially legacy PyPI to support respecting it at least for
reStructured text and Markdown (treating others as plain text)
- PyPUG again to provide usage docs once the default tools support it

Cheers,
Nick.

>
>
> —
> Donald Stufft
>
>
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] Alternate long_description formats, server-side

[Donald Stufft]

> On Jun 2, 2016, at 9:16 PM, Nick Timkovich  wrote:
> 
> I can definitely believe there are more important things to do, but some of 
> us aren't versed in the intricacies of what's up top and don't have the 
> familiarity to dive in. Us GitHub plebs are just raring to work on a feature 
> we think is within our grasp ;-)
> 

Yup! Nick was speaking to why folks like myself haven’t done it yet- If some 
enterprising person (perhaps you!) takes the time to write up a PEP and work it 
through the process, then there’s no reason to wait for me (or Nick, or any of 
the other core team) to do it :)


—
Donald Stufft



___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] Alternate long_description formats, server-side

[Nick Timkovich]

I can definitely believe there are more important things to do, but some of
us aren't versed in the intricacies of what's up top and don't have the
familiarity to dive in. Us GitHub plebs are just raring to work on a
feature we think is within our grasp ;-)

On Thu, Jun 2, 2016 at 7:35 PM, Nick Coghlan  wrote:

> On 2 June 2016 at 15:19, Donald Stufft  wrote:
> > On Jun 2, 2016, at 6:08 PM, Nick Timkovich 
> wrote:
> > So yea, we need some sort of standard. It could be as simple as just
> adding
> > a field to the existing metadata specification with something like:
> >
> > Description-Format: txt|rst|md|whatever
> >
> > With the assumption that if you omit the field then we do the legacy
> > behavior of “attempt to render as rst, fallback to plain text”. You’ll
> > probably want a registry of recommended values (or perhaps, mandatory
> > values? How do we add a new type of format to the list?).
> >
> > Anyways, just an off the cuff idea, but I don’t think there’s anyone
> > seriously opposed to the idea.
>
> Yep, it's not about opposition, just a matter of there being a range
> of more important problems ahead of it in the priority queue.
>
> That said, we do now have a mechanism to document additional metadata
> fields without requiring an entire new metadata version (see
> Provides-Extra in
> https://packaging.python.org/en/latest/specifications/#core-metadata
> for an example), and there's a catalog of anticipated formats in
> https://www.python.org/dev/peps/pep-0459/#document-names, so the idea
> of defining a Description-Format field sounds plausible to me (even if
> it takes a while for tools to start emitting or reading it).
>
> Cheers,
> Nick.
>
> --
> Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] Alternate long_description formats, server-side

[Nick Coghlan]

On 2 June 2016 at 15:19, Donald Stufft  wrote:
> On Jun 2, 2016, at 6:08 PM, Nick Timkovich  wrote:
> So yea, we need some sort of standard. It could be as simple as just adding
> a field to the existing metadata specification with something like:
>
> Description-Format: txt|rst|md|whatever
>
> With the assumption that if you omit the field then we do the legacy
> behavior of “attempt to render as rst, fallback to plain text”. You’ll
> probably want a registry of recommended values (or perhaps, mandatory
> values? How do we add a new type of format to the list?).
>
> Anyways, just an off the cuff idea, but I don’t think there’s anyone
> seriously opposed to the idea.

Yep, it's not about opposition, just a matter of there being a range
of more important problems ahead of it in the priority queue.

That said, we do now have a mechanism to document additional metadata
fields without requiring an entire new metadata version (see
Provides-Extra in
https://packaging.python.org/en/latest/specifications/#core-metadata
for an example), and there's a catalog of anticipated formats in
https://www.python.org/dev/peps/pep-0459/#document-names, so the idea
of defining a Description-Format field sounds plausible to me (even if
it takes a while for tools to start emitting or reading it).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] Alternate long_description formats, server-side

[Donald Stufft]

> On Jun 2, 2016, at 6:08 PM, Nick Timkovich  wrote:
> 
> When I brought up enabling Markdown previously, I was a bit over-eager and 
> started talking implementation before there was any sort of consensus about 
> it in principle, so it was a bit of a straw-man.
> 
> The previous discussion seemed to rest with the onus being on the user to do 
> it themselves, perhaps by installing (the non-Python) pandoc (non-trivial on 
> Windows) as well as pypandoc and then integrating it into twine or some such.
> 
> There seems to be a chasm between the GitHubbers that have various issues and 
> PRs to this effect on the pypa/readme_renderer repo that are met with a 
> frustrating silence from people with commit-power. Is the solution to 
> basically write a full spec (PEP?) before touching any code? That seems like 
> an actionable solution, but is it simply going to be rejected out-of-hand 
> because of the "just learn rST" sentiment among the maintainers?


Speaking with my PyPI and readme_renderer committer hat on, I have zero 
opposition to the idea of rendering Markdown (or any other alternative 
proposal)— in fact I think it’s all together a good thing. You’d need/want some 
buy-in from setuptools (likely Jason Coombs is all you need there) but I don’t 
think there’d be an issue actually adding it once there was some agreed upon 
thing.

So yea, we need some sort of standard. It could be as simple as just adding a 
field to the existing metadata specification with something like:

Description-Format: txt|rst|md|whatever

With the assumption that if you omit the field then we do the legacy behavior 
of “attempt to render as rst, fallback to plain text”. You’ll probably want a 
registry of recommended values (or perhaps, mandatory values? How do we add a 
new type of format to the list?). 

Anyways, just an off the cuff idea, but I don’t think there’s anyone seriously 
opposed to the idea.

—
Donald Stufft



___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig