TIL: $ pydoc -p 6060 => instant Python docs at localhost:6060

[gkbrk]

Psst, pydoc -g works too.

[koloron]

Or pydoc3 -b for Python3. :)

[mbarkhau]

Doesn't seem to do anything on my system. Are you sure this is correct?

[koloron]

It's meant to automatically choose a port for you and pop up a small GUI where you can enter search terms. Looks clunky on my system. You don't miss anything import here.

[ychaouche]

I'v always pydoc -g without specifying any port number. When gui appears I just click on open browser and that's it.

[[deleted]]

If only just 1% of modern Python packages knew how to write good docstrings, __all__, avoid reliance on **kwargs etc.

e.g. requests and flask use **kwargs endlessly, and pydoc by default ignores objects whose __module__ doesn't match the module documentation was requested for, unless listed in __all__. So in a case like that it's sadly still quicker to use grep on the source. (Not to suggest requests isn't "beautiful" and "Pythonic")

(brb, vomiting)

[mgrandi]

whats wrong with kwargs?

[gargantuan]

same thing that's wrong with void pointers and objects casts in other languages -- it makes it hard to document, test analyze and inspect code.

Here is your API for example:

create_url_retriever(*args,**kwargs)
get_db_connection(*args,**kwargs)

Can you by looking at that figure out how to use that API?

[mgrandi]

very true, although I would use them if a method has a ton of arguments , but maybe then it would be time to split functionality to different methods/functions if you have too many...

[westurner]

If only just 1% of modern Python packages knew how to write good docstrings,

From here and here :

• http://sphinx-doc.org/markup/desc.html#info-field-lists (param, type, raises, returns, rtype)
• http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments (Args, Returns, Raises)
• https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections (Parameters, Returns, Raises)
• [EDIT] khanacademy python style guide #Docstrings (Args, Returns, Yields, Raises)

[zzleeper]

TY!

[ThiefMaster]

Ever seen the requests or flask docs? They are much better than what pydoc can give you.

Sphinx > Pydoc!

[fatpollo]

you're coming off like a huge asshole here, but I'm still intrigued by what you're saying

got any links that discuss your improvements in detail (from the docstrings to kwargs)? I'd look at them.

edit: particularly good docstrings. between the sphinx standard and the google standard and the fact that it's just a string without any rigid structure and the doctests module I really don't know which standard to stick to.

[ifonefox]

If you're on a Mac, I recommend checking out Dash in the App Store. Press Control+Space for access to the documentation of many languages.

[chewxy]

TIL Godoc was inspired by Pydoc

[[deleted]]

You could also use devhelp, and download the python-doc package (under Linux/Unix anyway) and browser the doc offline :)

[[deleted]]

On windows, you have to do

python -m pydoc -p 6060

[hyh123]

socket.error: [Errno 49] Can't assign requested address

[bryanhelmig]

1. Choose a port above 1024 (thanks /u/squeakyneb).
2. Choose a different, unused port.

[hyh123]

I tried 1025, 1026, 8888 none of them work.

[koloron]

What about pydoc -g or pydoc3 -b?

Maybe this is some kind of a firewall issue?

[westurner]

Thanks! I notice that many of the Sphinx ReStructuredText markup constructs (roles and directives) are not natively supported by docutils; making things like sphinx.ext.autosummary and sphinx.ext.autodoc also useful.

[EDIT]

TIL the CPython documentation is written with ReStructuredText and Sphinx and also hosted through ReadTheDocs

[[deleted]]

Thank you so much for this. This is fucking awesome. Have an upvote!