[Distutils] advice re: packaging tasks

Marius Gedminas marius at pov.lt
Fri Oct 3 16:23:57 CEST 2014

On Thu, Oct 02, 2014 at 09:15:54AM -0700, Chris Jerdonek wrote:
> On Thu, Oct 2, 2014 at 8:08 AM, Marius Gedminas <marius at pov.lt> wrote:
> > I wrote restview for a different purpose, but found it rather useful for
> > discovering ReStructuredText problems that would make PyPI's fall back
> > to plaintext rendering.
> >
> > If you run
> >
> >   restview --long-description
> >
> > in a directory containing a setup.py, it'll invoke `python setup.py
> > --long-description' and interpret it using the same docutils settings as
> > PyPI, highlighting any errors.
> >
> > For a more automated (but perhaps less accurate) solution I pipe
> >
> >   python setup.py --long-description | rst2html > /dev/null
> Yes, I had been familiar with this latter approach.  It is documented here:
> https://docs.python.org/2/distutils/packageindex.html#pypi-package-display
> It did not work for me in my case though.  I eventually found that my
> use of URL fragments to link to sections elsewhere on the same page,
> and using relative links (supported by GitHub,
> https://github.com/blog/1395-relative-links-in-markup-files ) are what
> broke things.

Incidentally, this gotcha is why restview now has a --pypi-strict mode:

(This is enabled by default for restview --long-description.)

> Here is a link to a PyPI bug report regarding making it easier to find
> such issues:
> https://bitbucket.org/pypa/pypi/issue/161/rest-formatting-fails-and-there-is-no-way
> If people are interested, I wrote a pandoc filter to convert such
> links to things that will continue to work once uploaded to PyPI:
> https://gist.github.com/cjerdonek/76608610df43fd5b0fc3
> >> Lastly, as these setup-related tasks grow larger and more complicated,
> >> I found it helped to break them out into a separate setup package that
> >> sits alongside my project's main package library (and even adding
> >> tests in some cases).  Is this normal?  Have other people run into
> >> this?
> >
> > I'm not sure what you mean.  Do you have any examples?
> I mean that if you are working on project MyProject with package
> myproject inside the repo, you might find yourself adding ad hoc
> custom code to setup.py.  If this setup.py code starts to grow (a bit
> like your Makefile may grow), it might make sense to move some of the
> setup code to a package called something like myproject_setup
> alongside myproject (which would be used only for setup tasks).  And
> if this setup code was sufficiently complicated, you might find
> yourself wanting to add unit tests for some of it, so you might have
> myproject_setup/tests (and even testing it as part of your automated
> tests, etc).

Right.  I wanted to see some concrete examples of that code you find
putting in your setup.py files.

All I've seen before were bits that concatenate README.rst + CHANGES.rst
into a long_description, or parse the version number from some source
file in the name of DRY.

Marius Gedminas
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: Digital signature
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20141003/875f802f/attachment.sig>

More information about the Distutils-SIG mailing list