ENH: Quick access to online documentation #1937

Merged
merged 3 commits into from Sep 18, 2014

Projects

None yet

4 participants

@bashtage
Contributor

Adds a simple function to the api which allows the online documentation to be
accessed in the default browser. Has three modes:

  • Default: open the documentation page
  • String: search for the input
  • Function or class: go directly to the generated documentation
@bashtage
Contributor

Not sure this is readily testable on Travis

@coveralls

Coverage Status

Coverage decreased (-0.03%) when pulling df22130 on bashtage:web-doc into 957a43e on statsmodels:master.

@jseabold jseabold commented on an outdated diff Aug 27, 2014
statsmodels/tools/web.py
@@ -0,0 +1,48 @@
+"""
+Provides a function to open the system browser to either search or go directly
+to a function's reference
+"""
+import webbrowser
+import urllib
+
+BASE_URL = 'http://statsmodels.sourceforge.net/stable/'
@jseabold
jseabold Aug 27, 2014 Member

maybe make stable vs. devel an argument?

@jseabold
jseabold Aug 27, 2014 Member

Better yet you can check sm.version.release

@jseabold jseabold and 1 other commented on an outdated diff Aug 27, 2014
statsmodels/tools/web.py
@@ -0,0 +1,48 @@
+"""
+Provides a function to open the system browser to either search or go directly
+to a function's reference
+"""
+import webbrowser
+import urllib
+
+BASE_URL = 'http://statsmodels.sourceforge.net/stable/'
+
+
+def doc(arg=None):
@jseabold
jseabold Aug 27, 2014 Member

maybe something like online_doc or browse_doc or doc_browse would be more descriptive?

@josef-pkt
josef-pkt Aug 27, 2014 Member

api.py has an optional open_help that I had added for opening the html help
I think function name should start with open_

@josef-pkt
Member

I tried something similar for the htmlhelp, statsmodels.chm
What I didn't like so much with the search functionality was that it opens a new instance at each call to the function. I didn't manage to figure out a way to keep access to the Windows htmlhelp process.

But maybe it could be made to work for the webbrowser by holding on to the instance.
???

@bashtage
Contributor

I have incorporated most of these, and is now named open_doc. Ideally it would have a method to open local docs if present, or open web docs if not. Perhaps local docs should be installable in .statsmodels, like how IPython allows mathjax to be locally installed. Don't know how feasible this is.

As far as holding onto the browser, this will just launch a new window/tab (depends on platform and system browser), which is reasonable IMO.

@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling ffca794 on bashtage:web-doc into 957a43e on statsmodels:master.

@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling fb875cf on bashtage:web-doc into 957a43e on statsmodels:master.

@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling 0ed6ea5 on bashtage:web-doc into 957a43e on statsmodels:master.

@bashtage
Contributor

Not sure about the name -- I think it should be as simple and direct as possible, and using a _ is essentially the same as having 2 words. Maybe webhelp or webdoc.

@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling ace6cc2 on bashtage:web-doc into 957a43e on statsmodels:master.

@josef-pkt
Member

about the name:

This will be accessed almost exclusively through sm. which should almost always have tab completion, so I think having an informative, discoverable name is more important than being very short.
The initial reason that I picked open_ is to signal that this actually opens an external non-python process, in contrast to getting help inside the running interpreter.

@bashtage
Contributor

I think the doc string can explain what it does - having the name short and tempting might make it more likely to be used. Should throw in an unused URL variable which would allow tracking (e.g. &source=terminal), assuming stats are available from sourceforge

@josef-pkt
Member

Ok, either webdocs or webhelp sounds fine with me, web will remind users enough that it's not in the interpreter.
I checked sourceforge, we can download the access logs for the project.

Kevin Sheppard added some commits Aug 27, 2014
Kevin Sheppard ENH: Quick access to online documentation
Adds a simple function to the api which allows the online documentation to be
accessed in the default browser.  Has three modes:

* Default: open the documentation page
* String: search for the input
* Function or class: go directly to the generated documentation
ac42588
Kevin Sheppard Changed name of doc to open_doc
Rewrote to be testable
Added method to choose stable or devel, with default to look at version
Added tests
Added compatibility code for Python2/3 urlencode
f2f5e5a
Kevin Sheppard Renamed open_doc to webdoc
0a7eea0
@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling 0a7eea0 on bashtage:web-doc into 9ce1605 on statsmodels:master.

@coveralls

Coverage Status

Coverage increased (+0.02%) when pulling 0a7eea0 on bashtage:web-doc into 9ce1605 on statsmodels:master.

@josef-pkt
Member

It works for me, using python 2.7.
Sourceforge was very slow for the first search, but fast on subsequent searches.

merging

@josef-pkt josef-pkt merged commit ce2adc0 into statsmodels:master Sep 18, 2014

2 checks passed

continuous-integration/appveyor AppVeyor build succeeded
Details
continuous-integration/travis-ci The Travis CI build passed
Details
@josef-pkt
Member

This will need some advertising, should be added somewhere in the docs.
Otherwise users will find it only by chance.

@bashtage
Contributor

@josef-pkt I'll do a PR to work in an example of using it in an obvious place

@bashtage bashtage deleted the bashtage:web-doc branch Sep 30, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment