Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Quick access to online documentation #1937

Merged
merged 3 commits into from Sep 18, 2014

Conversation

Projects
None yet
4 participants
@bashtage
Copy link
Contributor

commented Aug 27, 2014

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

This comment has been minimized.

Copy link
Contributor Author

commented Aug 27, 2014

Not sure this is readily testable on Travis

@coveralls

This comment has been minimized.

Copy link

commented Aug 27, 2014

Coverage Status

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

import webbrowser
import urllib

BASE_URL = 'http://statsmodels.sourceforge.net/stable/'

This comment has been minimized.

Copy link
@jseabold

jseabold Aug 27, 2014

Member

maybe make stable vs. devel an argument?

This comment has been minimized.

Copy link
@jseabold

jseabold Aug 27, 2014

Member

Better yet you can check sm.version.release

BASE_URL = 'http://statsmodels.sourceforge.net/stable/'


def doc(arg=None):

This comment has been minimized.

Copy link
@jseabold

jseabold Aug 27, 2014

Member

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

This comment has been minimized.

Copy link
@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

This comment has been minimized.

Copy link
Member

commented Aug 27, 2014

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

This comment has been minimized.

Copy link
Contributor Author

commented Aug 27, 2014

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

This comment has been minimized.

Copy link

commented Aug 27, 2014

Coverage Status

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

@bashtage bashtage force-pushed the bashtage:web-doc branch 2 times, most recently from fb875cf to 0ed6ea5 Aug 27, 2014

@coveralls

This comment has been minimized.

Copy link

commented Aug 27, 2014

Coverage Status

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

@coveralls

This comment has been minimized.

Copy link

commented Aug 27, 2014

Coverage Status

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

@bashtage bashtage force-pushed the bashtage:web-doc branch from 0ed6ea5 to ace6cc2 Aug 27, 2014

@bashtage

This comment has been minimized.

Copy link
Contributor Author

commented Aug 27, 2014

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

This comment has been minimized.

Copy link

commented Aug 27, 2014

Coverage Status

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

@josef-pkt

This comment has been minimized.

Copy link
Member

commented Aug 27, 2014

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

This comment has been minimized.

Copy link
Contributor Author

commented Aug 27, 2014

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

This comment has been minimized.

Copy link
Member

commented Aug 28, 2014

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
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
Kevin Sheppard

@bashtage bashtage force-pushed the bashtage:web-doc branch from 542e392 to 0a7eea0 Aug 28, 2014

@coveralls

This comment has been minimized.

Copy link

commented Aug 28, 2014

Coverage Status

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

@coveralls

This comment has been minimized.

Copy link

commented Aug 28, 2014

Coverage Status

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

@josef-pkt

This comment has been minimized.

Copy link
Member

commented Sep 18, 2014

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

merging

josef-pkt added a commit that referenced this pull request Sep 18, 2014

Merge pull request #1937 from bashtage/web-doc
ENH/DOC: Quick access to online documentation

@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

This comment has been minimized.

Copy link
Member

commented Sep 18, 2014

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

@bashtage

This comment has been minimized.

Copy link
Contributor Author

commented Sep 18, 2014

@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
You can’t perform that action at this time.