[SUGGESTION] "find" in the built-in docs

[Webmaster4o]

When you search the docs, you can search for any term and find a page it's in. However, it's often the case that once you open the page, it's a huge long thing, and you can't find what you were looking for. (Sometimes the table of contents isn't descriptive enough). Therefore, it'd be great to have find in the docs. More than once I've found myself searching the built-in docs for something, then opening the same page in Safari just to do a find for the term I searched for! This would be super easy to implement and very helpful.

[omz]

I know this isn't what you're asking for, but it might still be useful in case you're not aware of it: On an iPad, you can tap the title of a documentation page to get an outline (list of functions, classes...), similar to the editor's.

[Olaf]

+1 your request, @Webmaster4o

Meanwhile, this also isn't what you look for, and far from ideal, but you could consider opening the source to the documentation in the editor and search then, like:

'''Open documentation source text file in editor, proof of concept needs further work'''
#TODO: doesn't work for builtins (so not e.g. sys)
#TODO: only works for standard Python modules (pylib, so not e.g. scene or NUMPY)
#TODO: doesn't work for submodules (e.g. os.path)
#TODO: opens already-open text files in another tab
#TODO: error handling

import os, editor

def dirname(path, n=1):
    return path if n<=0 else dirname(os.path.dirname(path), n-1)
def opendoctxt(module):
    path = module.__file__
    basename = os.path.splitext(os.path.basename(path))[0] + '.txt'
    txtpath = os.path.join(dirname(path, 4), 'Documentation','_sources', 'library', basename)
    editor.open_file(txtpath, True)

opendoctxt(os)

[Olaf]

By the way, this approach (below) also permits a second help tab open (in a browser), next to the regular one (help function), which may be helpful to toggle back and forth between two topics

'''Open 2nd tab on help in browser (next to regular help function), proof of concept needs further work'''

import os, webbrowser

def dirname(path, n=1):
    return path if n<=0 else dirname(os.path.dirname(path), n-1)
def openhelp():
    path = os.__file__
    txtpath = os.path.join(dirname(path, 4), 'Documentation', 'index.html')
    webbrowser.open('file://'+txtpath)

openhelp()

[omz]

Here's a little hack that adds a search button to the documentation browser. It pops up a text input dialog, highlights all occurrences of the given word on the page, and scrolls to the first occurrence. As I said, it's a hack, not thoroughly tested, and it may break in future versions of Pythonista.

# Adds a "Find on page" button to the documentation browser.
# NOTE: Only intended for iPad, probably doesn't work correctly on iPhone.

from objc_util import *
import console
UIBarButtonItem = ObjCClass('UIBarButtonItem')

js_tpl = '''
// http://james.padolsey.com/snippets/highlighting-text-with-javascript/
function highlight(container, what) {
    var content = container.innerHTML,
        pattern = new RegExp('(>[^<.]*)(' + what + ')([^<.]*)','gi'),
        replaceWith = '$1<span style="background-color:yellow" class="search-highlight">$2</span>$3',
        highlighted = content.replace(pattern,replaceWith);
    return (container.innerHTML = highlighted) !== content;
}
// http://stackoverflow.com/a/11986374
function findPos(obj) {
    var curtop = 0;
    if (obj.offsetParent) {
        do {
            curtop += obj.offsetTop;
        } while (obj = obj.offsetParent);
    return [curtop];
    }
}
highlight(document.body, '{TERM}');
window.scroll(0, findPos(document.getElementsByClassName("search-highlight")[0]));
'''

def get_accessory_tab_vc():
	root_vc = UIApplication.sharedApplication().keyWindow().rootViewController()
	tab_vc = root_vc.accessoryViewController()
	return tab_vc
	
def get_docs_vc():
	tab_vc = get_accessory_tab_vc()
	if not tab_vc.documentationViewController():
		tab_vc.showDocumentation()
	return tab_vc.documentationViewController()

def searchAction(_self, _cmd):
	term = console.input_alert('Search on page')
	doc_vc = get_docs_vc()
	webview = doc_vc.webView()
	search_js = js_tpl.replace('{TERM}', term)
	webview.stringByEvaluatingJavaScriptFromString_(search_js)
	
DocSearchHandler = create_objc_class('DocSearchHandler', methods=[searchAction])

@on_main_thread
def add_search_button():
	doc_vc = get_docs_vc()
	buttons = doc_vc.navigationItem().rightBarButtonItems().mutableCopy().autorelease()
	if len(buttons) > 1:
		return
	search_img = UIImage.imageNamed_('Search')
	handler = DocSearchHandler.new()
	search_button = (UIBarButtonItem.alloc()
		.initWithImage_style_target_action_(search_img, 0, handler, 'searchAction'))
	buttons.addObject_(search_button)
	doc_vc.navigationItem().rightBarButtonItems = buttons
	tab_vc = get_accessory_tab_vc()
	tab_vc.reloadBarButtonItemsForSelectedTab()

add_search_button()

[Webmaster4o]

Woah, @omz, that's awesome.

[trey]

I know this thread is 4 years old so I probably shouldn’t expect the code to work, but if I just run it I get:

Traceback (most recent call last):
  File "_ctypes/callbacks.c", line 234, in 'calling callback function'
  File "/var/containers/Bundle/Application/1F6E6781-AC43-4C6A-86CC-E1540DE81702/Pythonista3.app/Frameworks/Py3Kit.framework/pylib/site-packages/objc_util.py", line 1066, in OMMainThreadDispatcher_invoke_imp
    retval = func(*args, **kwargs)
  File "/private/var/mobile/Library/Mobile Documents/iCloud~com~omz-software~Pythonista3/Documents/my-tools/find-on-docpage.py", line 68, in add_search_button
    doc_vc = get_docs_vc()
  File "/private/var/mobile/Library/Mobile Documents/iCloud~com~omz-software~Pythonista3/Documents/my-tools/find-on-docpage.py", line 49, in get_docs_vc
    if not tab_vc.documentationViewController():
  File "/var/containers/Bundle/Application/1F6E6781-AC43-4C6A-86CC-E1540DE81702/Pythonista3.app/Frameworks/Py3Kit.framework/pylib/site-packages/objc_util.py", line 798, in __call__
    method_name, kwarg_order = resolve_instance_method(obj, self.name, args, kwargs)
  File "/var/containers/Bundle/Application/1F6E6781-AC43-4C6A-86CC-E1540DE81702/Pythonista3.app/Frameworks/Py3Kit.framework/pylib/site-packages/objc_util.py", line 405, in resolve_instance_method
    raise AttributeError('No method found for %s' % (name,))
AttributeError: No method found for documentationViewController

(This post is now too long for me too see what I’m typing in the viewport, even maximized to the whole iPad screen, and there’s apparently no way to scroll, so I apologize if I have typoes belowe...)

Perhaps my error is that I shouldn’t be running the script, but in some other way install it, as you do with extensions?

Even if this doesn’t work anymore, a different method would be welcomed—I read the earlier comment saying to tap the title to get a tree traversal, like with code view, but I can’t figure out how to do that for the documentation—unlike the code, where there’s a centered title up top you can tap the documentation has an interface without a title bar at top, the search box replaces it—and that search box searches globally through the docs. Right now I’m looking at a method and I want to see if the argument name mentioned here is discussed anywhere else, but argument names aren’t indexed so I can’t find them via the search, I need a “search in page”, but a hierarchy view might give me a clue.

The online docs, where I could use the ⌘ F in the browser, are problematic when I’m on VPN because the HTTPS link doesn’t work as the certificate has expired.

Thanks!

p.s. Ooh! “edit” works to get the viewport to the bottom though it doesn’t scroll up, so I’ll try to fix this mess now.... this is current Safari on current iPadOS 13 on an iPad Pro 10.5” using a Bluetooth keyboard, btw, since I assume this limitation isn’t universal!