rtfd/readthedocs.org — Issue #166: F1
Author: miohtama
Created: 2012-02-17 22:12:57+00:00
State: open

A generic on-line cross-package Python help.

Does anyone remember those 90s Turbo Pascal and Turbo C IDEs where you could press F1 on a function and get on-line help? The software development world has greatly progressed since these medieval times, but the need for help/docs is still there.

Because...

* Software is no longer monolithic controlled by one party (maybe excluding Microsoft), but heterogenous world of different packages

* Software is no longer developed in one de facto IDE, but various tools from VIM to AJAX based editors like ACE

...providing on-line help is not that easy. My F1 key is useless.

Now, ladies and gentlemen, I propose we fix this once for all for Python development world, setting an example all other inferior programming languages can follow.

Vision

* Most of Python documentation is uploaded to readthedocs.org in some point of the future

* Most of Python docs would have some kind of mechanism to resolve dotted names to their API documentation (don't know how well Sphinx handles this currently)

* The user presses F1 key on his/her editor over a function name

* It is editor's responsibility to figure out the full dotted name of this function (easy for modules, little bit challenging for object instances, but it's out of the scope of this issue)

* readthedocs.org provides an AJAX interface where you can pass in a Python dotted name e.g.

http;//readthedocs.org/online-help?name=os.path.dirname

* This will be resolved to a Python documentation hosted on RTD, by cross-searched across index of ALL known Python package documentation

* The corresponding API doc bit for the dotted name is returned as HTML payload

* If there are several overlapping matches, e.g. different packages provide the same dotted path, a HTML payload with selector is provided which will contain more accurate links

django.foobar.function from FOOBAR project

django.foobar.function from MIKKO's KENNEL MANAGER PROJECT

# where the link would be http;//readthedocs.org/online-help?name=os.path.dirname&projectId=mikko-doghouse

Benefits

* This way we can offload the responsibility of API on-line help maintenance from IDE authors to centralized open source service

* RTD and Sphinx provides de facto standard interface for accessing, uploading, formatting and maintaining API docs

* Everyone loves RTD