Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Re-organize to make plug-in auto-update compatible
 * Added a Makefile that automates preparing ZIP files for http://www.vim.org
 * The Makefile generates README.html <- README.md and includes it in the ZIP
 * The ZIP files can be directly unpacked in ~/.vim/ to ease installation
 * Changed install instructions to download ZIP instead of individual files
 * Renamed `vimpythonindex` since it should be installed as ~/.vim/pyref/index
 * Renamed `create-index.py` to `spider.py`
 * The plug-in should now support automatic updates using `getscript.vim`
 * Support for exceptions imported from the `exceptions` module
  • Loading branch information
xolox committed Jun 3, 2010
1 parent 218990f commit 16ba180
Show file tree
Hide file tree
Showing 7 changed files with 131 additions and 62 deletions.
23 changes: 23 additions & 0 deletions Makefile
@@ -0,0 +1,23 @@
OUTDOC=doc/README.html
ZIPDIR := $(shell mktemp -d)
ZIPFILE := $(shell mktemp -u)

# NOTE: Make does NOT expand the following back ticks!
VERSION=`grep '^" Version:' pyref.vim | awk '{print $$3}'`

# The main rule builds a ZIP that can be published to http://www.vim.org.
main: Makefile pyref.vim index spider.py $(OUTDOC)
@echo "Creating \`pyref-$(VERSION).zip' .."
@mkdir -p $(ZIPDIR)/plugin $(ZIPDIR)/pyref
@cp pyref.vim $(ZIPDIR)/plugin
@cp index $(OUTDOC) spider.py $(ZIPDIR)/pyref
@cd $(ZIPDIR) && zip -r $(ZIPFILE) . >/dev/null
@rm -R $(ZIPDIR)
@mv $(ZIPFILE) pyref-$(VERSION).zip

# This rule converts the Markdown README to HTML, which reads easier.
$(OUTDOC): Makefile README.md
@echo "Creating $(OUTDOC) .."
@cat doc/README.header > $(OUTDOC)
@markdown README.md >> $(OUTDOC)
@cat doc/README.footer >> $(OUTDOC)
27 changes: 14 additions & 13 deletions README.md
Expand Up @@ -13,18 +13,15 @@ Google Chrome.

The search works by scanning through a special index file with keyword, URL
pairs separated by tabs and delimited by newlines. You can create this index
yourself using a Python script I've written (see the file [create-index.py]
[view_spider]) or you can download the index that I've already created (see
the file [vimpythonindex] [view_index]).
yourself using a Python script I've written (see the file [spider.py]
[view_spider]) or you can download the index that I've already created (see the
file [index] [view_index]).

## Usage and options

Right-click and save the file [pyref.vim][download_plugin] as
`~/.vim/plugin/pyref.vim` (if you're on Windows save the file as
`%USERPROFILE%\vimfiles\plugin\pyref.vim` instead), likewise save the file
[vimpythonindex][download_index] as `~/.vimpythonindex` (if you're on Windows
then save this file as `%USERPROFILE%\_vimpythonindex` instead) and restart
Vim. Now try it out: Open some Python source code in Vim and press the `<F1>`
Unzip the most recent [ZIP archive] [latest_zip] file inside your Vim profile
directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on
Windows), restart Vim and try it out: Open a Python script and press the `<F1>`
key. If it doesn't work at first, please see the `pyref_browser` and
`pyref_mapping` options below.

Expand Down Expand Up @@ -71,9 +68,11 @@ the global variable `pyref_mirror` accordingly.
### The `pyref_index` option

If you don't like the default location of the index file you can change it by
setting the global variable `pyref_index`. Note that a leading `~` in the path
is expanded to your current home directory (`$HOME` on UNIX, `%USERPROFILE%` on
Windows).
setting the global variable `pyref_index`. A leading `~` in the `pyref_index`
variable is expanded to your current home directory (`$HOME` on UNIX,
`%USERPROFILE%` on Windows). Be aware that when you change the `pyref_index`
option automatic updates using the [getscript plug-in] [getscript_usage] won't
update the index file anymore!

### General note about options

Expand All @@ -88,7 +87,7 @@ have to query the file-system when it's loaded.
If you have questions, bug reports, suggestions, etc. the author can be
contacted at <peter@peterodding.com>. The latest version is available
at <http://peterodding.com/code/vim/pyref> and <http://github.com/xolox/vim-pyref>.
If you like the script please vote for it on [vim.org][vim_scripts_entry].
If you like the script please vote for it on [www.vim.org][vim_scripts_entry].

## License

Expand All @@ -98,6 +97,8 @@ Vim-PyRef is licensed under the [MIT license] [mit_license].<br>

[download_index]: http://github.com/xolox/vim-pyref/raw/master/vimpythonindex
[download_plugin]: http://github.com/xolox/vim-pyref/raw/master/pyref.vim
[getscript_usage]: http://vimdoc.sourceforge.net/htmldoc/pi_getscript.html#glvs-usage
[latest_zip]: http://github.com/downloads/xolox/vim-pyref/pyref-latest.zip
[mit_license]: http://en.wikipedia.org/wiki/MIT_License
[pylangref]: http://docs.python.org/reference/index.html
[pylibref]: http://docs.python.org/library/index.html
Expand Down
2 changes: 2 additions & 0 deletions doc/README.footer
@@ -0,0 +1,2 @@
</body>
</html>
20 changes: 20 additions & 0 deletions doc/README.header
@@ -0,0 +1,20 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>pyref.vim - Context-sensitive documentation for Python source code in Vim</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
body { font-family: sans-serif; padding: 1em 30% 4em 1em; }
a:link, a:visited { color: #000080; }
a:hover, a:active { color: #8B0000; }
pre, code, tt { font-family: Monaco, Consolas, monospace; }
pre { margin-left: 2em; }
code { background: #F6F6F6; padding: .1em .3em; }
p { text-align: justify; line-height: 1.75em; }
h1 { padding: 0 30% 0 0; }
h2, h3 { border-bottom: 2px solid #F6F6F6; margin: 2em 0 -0.5em 0; padding-left: 0.5em; }
hr { height: 0; border: none; border: 1px solid #F6F6F6; }
</style>
</head>
<body>
File renamed without changes.
121 changes: 72 additions & 49 deletions pyref.vim
Expand Up @@ -3,65 +3,88 @@
" Last Change: June 3, 2010
" URL: http://peterodding.com/code/vim/pyref
" License: MIT
" Version: 0.4

" Configuration defaults. {{{1
" Support for automatic update using the GLVS plug-in.
" GetLatestVimScripts: 3104 1 :AutoInstall: pyref.zip

if !exists('pyref_index')
if has('win32') || has('win64')
let pyref_index = '~/_vimpythonindex'
else
let pyref_index = '~/.vimpythonindex'
endif
" Don't source the plug-in when its already been loaded or &compatible is set.
if &cp || exists('loaded_pyref')
finish
endif

if !exists('pyref_mirror')
let s:local_mirror = '/usr/share/doc/python2.6/html'
if isdirectory(s:local_mirror)
let pyref_mirror = 'file://' . s:local_mirror
else
let pyref_mirror = 'http://docs.python.org'
endif
unlet s:local_mirror
endif
" Configuration defaults. {{{1

if !exists('pyref_mapping')
let pyref_mapping = '<F1>'
endif
" Use a script-local function to define the configuration defaults so that we
" don't pollute Vim's global scope with temporary variables.

if !exists('pyref_browser')
if has('win32') || has('win64')
" On Windows the default web browser is accessible using the START command.
let pyref_browser = 'CMD /C START ""'
else
" On UNIX we decide whether to use a CLI or GUI web browser based on
" whether the $DISPLAY environment variable is set.
if $DISPLAY == ''
let s:known_browsers = ['lynx', 'links', 'w3m']
function! s:CheckOptions()
if !exists('g:pyref_mapping')
let g:pyref_mapping = '<F1>'
endif
if !exists('g:pyref_mirror')
let local_mirror = '/usr/share/doc/python2.6/html'
if isdirectory(local_mirror)
let g:pyref_mirror = 'file://' . local_mirror
else
" Note: Don't use `xdg-open' here, it ignores fragment identifiers :-S
let s:known_browsers = ['gnome-open', 'firefox', 'google-chrome', 'konqueror']
let g:pyref_mirror = 'http://docs.python.org'
endif
" Otherwise we search for a sensible default browser.
let s:search_path = substitute(substitute($PATH, ',', '\\,', 'g'), ':', ',', 'g')
for s:browser in s:known_browsers
" Use globpath()'s third argument where possible (since Vim 7.3?).
try
let s:matches = split(globpath(s:search_path, s:browser, 1), '\n')
catch
let s:matches = split(globpath(s:search_path, s:browser), '\n')
endtry
if len(s:matches) > 0
let pyref_browser = s:matches[0]
break
endif
if !exists('g:pyref_index')
if has('win32') || has('win64')
let g:pyref_index = '~/vimfiles/pyref/index'
else
let g:pyref_index = '~/.vim/pyref/index'
endif
endif
if !filereadable(fnamemodify(g:pyref_index, ':p'))
let msg = "pyref.vim: The index file doesn't exist or isn't readable! (%s)"
echoerr printf(msg, g:pyref_index)
return 0 " Initialization failed.
endif
if !exists('g:pyref_browser')
if has('win32') || has('win64')
" On Windows the default web browser is accessible using the START command.
let g:pyref_browser = 'CMD /C START ""'
else
" On UNIX we decide whether to use a CLI or GUI web browser based on
" whether the $DISPLAY environment variable is set.
if $DISPLAY == ''
let known_browsers = ['lynx', 'links', 'w3m']
else
" Note: Don't use `xdg-open' here, it ignores fragment identifiers :-S
let known_browsers = ['gnome-open', 'firefox', 'google-chrome', 'konqueror']
endif
" Otherwise we search for a sensible default browser.
let search_path = substitute(substitute($PATH, ',', '\\,', 'g'), ':', ',', 'g')
for browser in known_browsers
" Use globpath()'s third argument where possible (since Vim 7.3?).
try
let matches = split(globpath(search_path, browser, 1), '\n')
catch
let matches = split(globpath(search_path, browser), '\n')
endtry
if len(matches) > 0
let g:pyref_browser = matches[0]
break
endif
endfor
if !exists('g:pyref_browser')
let msg = "pyref.vim: Failed to find a default web browser!"
echoerr msg . "\nPlease set the global variable `pyref_browser' manually."
return 0 " Initialization failed.
endif
endfor
unlet s:search_path s:known_browsers s:browser s:matches
if !exists('pyref_browser')
let message = "pyref.vim: Failed to find a default web browser!"
echoerr message . "\nPlease set the global variable `pyref_browser' manually."
finish
endif
endif
return 1 " Initialization successful.
endfunction

if s:CheckOptions()
" Don't reload the plug-in once its been successfully initialized.
let loaded_pyref = 1
else
" Don't finish sourcing the script when there's no point.
finish
endif

" Automatic command to define key-mapping. {{{1
Expand Down Expand Up @@ -109,7 +132,7 @@ function! s:PyRef() " {{{1
let lines = []
echoerr "pyref.vim: Failed to read index file! (" . indexfile . ")"
endtry
if s:JumpToEntry(lines, '^\(module-\)\?' . pattern . '\t')
if s:JumpToEntry(lines, '^\(module-\|exceptions\.\)\?' . pattern . '\t')
return
endif

Expand Down
File renamed without changes.

0 comments on commit 16ba180

Please sign in to comment.