[Python-ideas] docs.python.org: Short URLs

Markus Unterwaditzer markus at unterwaditzer.net
Mon Feb 17 14:12:44 CET 2014


http://cryto.net/~joepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/

A few of you might have read that infamous rant about Python's community and
documentation and Brian Curtins response:
http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html

Like Brian, i think that the unconstructive tone ruined the points the author
was trying to make, a part of which i actually agree with. So, here is an
attempt at a positive consequence of this rant.

The author talks about the inaccessibility of Python's documentation via Google
compared to PHP's. One can easily verify that by themselves: Just enter the
name of any builtin into the search engine at docs.python.org, such as str,
float, or print. In none of these cases, the appropriate documentation is the
first result. The search engine at php.net is, on the other hand, a breeze to
use, probably because the search engine doesn't have to take namespaces into
account when searching.

The suggestion i want to make isn't just "make the search engine better". I
know that such things are better filed against Sphinx.

What i actually wanted to suggest is a convenience feature that is available at
php.net: http://php.net/str_replace directly shows the documentation of PHP's
str_replace. Concretely, I propose that, for example,
http://docs.python.org/2/str redirects to the documentation for `str` in Python
2 , while http://docs.python.org/3/str, http://docs.python.org/str and/or
http://python.org/str redirect to the documentation for `str` in Python 3. Here
is a simple script that roughly shows how i would expect this redirect to
resolve the given object names:

    import sphinx.ext.intersphinx as intersphinx

    class FakeSphinxApp(object):
        def warn(self, x):
            print(x)

    baseurl = 'http://docs.python.org/3/'
    inv = intersphinx.fetch_inventory(FakeSphinxApp(), baseurl, baseurl + 'objects.inv')
    index = {}
    for value in inv.values():
        index.update(value)

    def url_for_object(s):
        return index[s][2]
    # >>> url_for_object('str')
    # 'http://docs.python.org/3/library/stdtypes.html#str'
    # >>> url_for_object('datetime.datetime')
    # 'http://docs.python.org/3/library/datetime.html#datetime.datetime'



I am aware that the pydoc command-line utility ships with the default
distribution of Python. However, i don't think any beginner wants to get in
touch with the command line more than what is absolutely neccessary, and i also
doubt that people are aware of this utility. I personally also haven't used
pydoc and Python's `help` builtin mostly because of this:

    $ pydoc datetime.datetime

    Help on class datetime in datetime:

    datetime.datetime = class datetime(date)
     |  datetime(year, month, day[, hour[, minute[, second[, microsecond[,tzinfo]]]]])
     |  
     |  The year, month and day arguments are required. tzinfo may be None, or an
     |  instance of a tzinfo subclass. The remaining arguments may be ints.
     |  
     |  Method resolution order:
     |      datetime
     |      date
     |      builtins.object
     |  
     |  Methods defined here:
     |  
     |  __add__(...)
     |      x.__add__(y) <==> x+y
     |  
     |  __eq__(...)
     |      x.__eq__(y) <==> x==y
     |  
     |  __ge__(...)
     |      x.__ge__(y) <==> x>=y
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     ...

What do you think?

-- Markus


More information about the Python-ideas mailing list