On Package Docs

Recently Danny Greenfeld posted an article and I must say +1 for everything in this post except the "Documentation" part.

I use RTFD myself and can't praise it enough, it really changes they way docs may be handled and is a big step forward (my personal favorite features are DVCS integration and hosting doc versions for every package release).

But there are large packages and small packages, and it is good to target small and focused packages. There are certainly a lot of packages that have to be large, and they need dedicated docs, and huge +1 then for having good docs hosted at RTFD.

But for small packages there is an another option: README.rst displayed directly at package's pypi page.

#!/usr/bin/env python
from distutils.core import setup

CHANGES = open('CHANGES.rst').read()
README = open('README.rst').read()

setup(
    name='my-fancy-package',
    long_description = "\n".join([README, CHANGES]),
    # ...
)

I think it makes more sense than providing full-blown docs hosted at RTFD for such packages,

README.rst share some benefits of the rtfd-hosted docs: it is hosted per-release and no additional steps are required to make it visible to users.

Even more, having README.rst may act as a reminder for a package author: if the package docs doesn't fit README.rst format it may mean that package itself does too much (and should be split) or is too complex to use (and should be simplified).

So I think sometimes not having docs at RTFD (and using README.rst instead) can be a good sign, not a bad sign for a package.

blog comments powered by Disqus