Help explorer widget supplying a simple web browser and a plain text help viewer

Classes:

HelpExplorer(*args, **kwargs)	A widget for showing the documentation.
HelpMixin()	Base class for providing help on an object
SphinxThread(outdir[, html_text_no_doc])	A thread to render sphinx documentation in a separate process
TextHelp(*args, **kwargs)	Class to show plain text rst docstrings
UrlBrowser(*args, **kwargs)	Very simple browser with session history and autocompletion based upon the PyQt5.QtWebEngineWidgets.QWebEngineView class
UrlCombo(*args, **kwargs)	A editable ComboBox with autocompletion
UrlHelp(*args, **kwargs)	Class to convert rst docstrings to html and show browsers

Functions:

file2html(fname)
html2file(url)

class psyplot_gui.help_explorer.HelpExplorer(*args, **kwargs)

Bases: QWidget, DockMixin

A widget for showing the documentation. It behaves somewhat similar to spyders object inspector plugin and can show restructured text either as html (if sphinx is installed) or as plain text. It furthermore has a browser to show html content

Warning

The HelpBrowser class is known to crash under PyQt4 when new web page domains are loaded. Hence you should disable the browsing to different remote websites and even disable intersphinx

Methods:

close(self)
set_viewer(name)	Sets the current documentation viewer
show_help(obj[, oname, files])	Show the documentaion of the given object
show_intro([text])	Show an intro text
show_rst(text[, oname, files])	Show restructured text

Attributes:

viewers

The viewer classes used by the help explorer.

close(self) → bool

set_viewer(name)

Sets the current documentation viewer

Parameters:

name (str or object) – A string must be one of the viewers attribute. An object can be one of the values in the viewers attribute

show_help(obj, oname='', files=None)

Show the documentaion of the given object

We first try to use the current viewer based upon it’s HelpMixin.can_document_object attribute. If this does not work, we check the other viewers

Parameters:

• obj (object) – The object to get the documentation for

• oname (str) – The name to use for the object in the documentation

• files (list of str) – A path to additional files that shall be used to process the docs

show_intro(text='')

Show an intro text

We first try to use the current viewer based upon it’s HelpMixin.can_show_rst attribute. If this does not work, we check the other viewers

Parameters:

s (str) – A string in reStructured Text format to show

show_rst(text, oname='', files=None)

Show restructured text

We first try to use the current viewer based upon it’s HelpMixin.can_show_rst attribute. If this does not work, we check the other viewers

Parameters:

• text (str) – The text to show

• oname (str) – The object name

• descriptor (instance of object_descriptor) – The object descriptor holding the informations

• files (list of str) – A path to additional files that shall be used to display the docs

viewers = {'HTML help': <class 'psyplot_gui.help_explorer.UrlHelp'>, 'Plain text': <class 'psyplot_gui.help_explorer.TextHelp'>}

The viewer classes used by the help explorer. HelpExplorer instances replace this attribute with the corresponding HelpMixin instance

class psyplot_gui.help_explorer.HelpMixin

Bases: object

Base class for providing help on an object

Attributes:

can_document_object	bool determining whether the documentation of an object can be shown or not
can_show_rst	bool determining whether this class can show restructured text

Methods:

describe_object(obj[, oname])	Return an instance of the object_descriptor class
get_doc(descriptor)	Get the documentation of the object in the given descriptor
header(descriptor, sig)	Format the header and include object name and signature sig
process_docstring(lines, descriptor)	Make final modification on the rst lines
show_help(obj[, oname, files])	Show the rst documentation for the given object
show_intro([text])	Show an intro message
show_rst(text[, oname, descriptor, files])	Abstract method which needs to be implemented by th widget to show restructured text

Classes:

object_descriptor

Object containing the necessary fields to describe an object given to the help widget.

can_document_object = True

bool determining whether the documentation of an object can be shown or not

can_show_rst = True

bool determining whether this class can show restructured text

describe_object(obj, oname='')

Return an instance of the object_descriptor class

Returns:

The descriptor containing the information on the object

Return type:

object_descriptor

get_doc(descriptor)

Get the documentation of the object in the given descriptor

Parameters:

descriptor (instance of object_descriptor) – The descriptor containig the information on the specific object

Returns:

The header and documentation of the object in the descriptor

Return type:

str

Notes

This method uses the IPython.core.oinspect.getdoc() function to get the documentation and the IPython.core.oinspect.signature() function to get the signature. Those function (different from the inspect module) do not fail when the object is not saved

header(descriptor, sig)

Format the header and include object name and signature sig

Returns:

The header for the documentation

Return type:

str

object_descriptor

Object containing the necessary fields to describe an object given to the help widget. The descriptor is set up by the describe_object() method.

alias of ObjectDescriptor Attributes:

name	Alias for field number 1
obj	Alias for field number 0

process_docstring(lines, descriptor)

Make final modification on the rst lines

Returns:

The docstring

Return type:

str

show_help(obj, oname='', files=None)

Show the rst documentation for the given object

Parameters:

• obj (object) – The object to get the documentation for

• oname (str) – The name to use for the object in the documentation

• files (list of str) – A path to additional files that shall be used to process the docs

show_intro(text='')

Show an intro message

Parameters:

s (str) – A string in reStructured Text format to show

show_rst(text, oname='', descriptor=None, files=None)

Abstract method which needs to be implemented by th widget to show restructured text

Parameters:

• text (str) – The text to show

• oname (str) – The object name

• descriptor (instance of object_descriptor) – The object descriptor holding the informations

• files (list of str) – A path to additional files that shall be used to display the docs

Returns:

True if the text is displayed

Return type:

bool

class psyplot_gui.help_explorer.SphinxThread(outdir, html_text_no_doc='')

Bases: QThread

A thread to render sphinx documentation in a separate process

Attributes:

html_error(*args, **kwargs)
html_ready(*args, **kwargs)	A signal to be emitted when the rendering finished.

Methods:

render(doc, name)	Render the given rst string and save the file as name + '.rst'
run()	Create the html file.

html_error(*args, **kwargs)

html_ready(*args, **kwargs)

A signal to be emitted when the rendering finished. The url is the file location

render(doc, name)

Render the given rst string and save the file as name + '.rst'

Parameters:

• doc (str) – The rst docstring

• name (str) – the name to use for the file

run()

Create the html file. When called the first time, it may take a while because the sphinx.application.Sphinx app is build, potentially with intersphinx

When finished, the html_ready signal is emitted

class psyplot_gui.help_explorer.TextHelp(*args, **kwargs)

Bases: QFrame, HelpMixin

Class to show plain text rst docstrings

Attributes:

editor

The PyQt5.QtWidgets.QPlainTextEdit instance used for displaying the documentation

Methods:

show_rst(text, *args, **kwargs)

Show the given text in the editor window

editor

The PyQt5.QtWidgets.QPlainTextEdit instance used for displaying the documentation

show_rst(text, *args, **kwargs)

Show the given text in the editor window

Parameters:

• text (str) – The text to show

• ``*args –

  Are ignored

• **kwargs`` –

  Are ignored

class psyplot_gui.help_explorer.UrlBrowser(*args, **kwargs)

Bases: QFrame

Very simple browser with session history and autocompletion based upon the PyQt5.QtWebEngineWidgets.QWebEngineView class

Warning

This class is known to crash under PyQt4 when new web page domains are loaded. Hence it should be handled with care

Methods:

browse(url)	Make a web browse on the given url and show the page on the Webview widget.
toogle_lock()	Disable (or enable) the changing of the current webpage
toogle_url_lock()	Disable (or enable) the loading of web pages in www
update_url_lock_from_rc(online)
url_changed(url)	Triggered when the url is changed to update the adress line

Attributes:

bt_ahead	button to go to next url
bt_back	button to go to previous url
bt_lock	button to go lock to the current url
bt_lock_default	default value for bt_lock.
bt_refresh	refresh the current url
bt_url_lock	button to disable browsing in www
bt_url_lock_default	default value for bt_url_lock.
button_box	The upper part of the browser containing all the buttons
completed	Boolean whether the html page loading is completed.
default_url	The initial url showed in the webview.
doc_urls
html	The actual widget showing the html content
tb_url	adress line
url_like_re
vbox	The upper most layout aranging the button box and the html widget

browse(url)

Make a web browse on the given url and show the page on the Webview widget.

bt_ahead = None

button to go to next url

bt_back = None

button to go to previous url

bt_lock = None

button to go lock to the current url

bt_lock_default = None

default value for bt_lock. Is set during browser initialization

bt_refresh = None

refresh the current url

bt_url_lock = None

button to disable browsing in www

bt_url_lock_default = None

default value for bt_url_lock. Is set during browser initialization

button_box = None

The upper part of the browser containing all the buttons

property completed

Boolean whether the html page loading is completed.

default_url = None

The initial url showed in the webview. If None, nothing will be displayed

doc_urls = {'cartopy': 'http://scitools.org.uk/cartopy/docs/latest/index.html', 'numpy': 'https://docs.scipy.org/doc/numpy/reference/routines.html', 'pandas': 'http://pandas.pydata.org/pandas-docs/stable/', 'psyplot': 'http://psyplot.github.io/psyplot/', 'pyplot': 'http://matplotlib.org/api/pyplot_api.html', 'seaborn': 'http://stanford.edu/~mwaskom/software/seaborn/api.html', 'startpage': 'https://startpage.com/', 'xarray': 'http://xarray.pydata.org/en/stable/'}

html

The actual widget showing the html content

tb_url = None

adress line

toogle_lock()

Disable (or enable) the changing of the current webpage

toogle_url_lock()

Disable (or enable) the loading of web pages in www

update_url_lock_from_rc(online)

url_changed(url)

Triggered when the url is changed to update the adress line

url_like_re = re.compile('^\\w+://')

vbox = None

The upper most layout aranging the button box and the html widget

class psyplot_gui.help_explorer.UrlCombo(*args, **kwargs)

Bases: QComboBox

A editable ComboBox with autocompletion

Methods:

add_text_on_top([text, block])	Add the given text as the first item
keyPressEvent(event)	Handle key press events
setModel(model)	Reimplemented to also set the model of the filter and completer

add_text_on_top(text=None, block=False)

Add the given text as the first item

keyPressEvent(event)

Handle key press events

setModel(model)

Reimplemented to also set the model of the filter and completer

class psyplot_gui.help_explorer.UrlHelp(*args, **kwargs)

Bases: UrlBrowser, HelpMixin

Class to convert rst docstrings to html and show browsers

Methods:

browse(url)	Reimplemented to add file paths to the url string
close(self)
describe_object(obj[, oname])	Describe an object using additionaly the object type from the get_objtype() method
get_doc(descriptor)	Reimplemented to (potentially) use the features from sphinx.ext.autodoc
get_objtype(obj)	Get the object type of the given object and determine wheter the object is considered a class, a module, a function, method or data
header(descriptor, sig)	Format the header and include object name and signature sig
is_importable(modname)	Determine whether members of the given module can be documented with sphinx by using the sphinx.util.get_module_source() function
process_docstring(lines, descriptor)	Process the lines with the napoleon sphinx extension
reset_sphinx(value)	Method that is called if the configuration changes
show_help(obj[, oname, files])	Render the rst docu for the given object with sphinx and show it
show_intro([text])	Show the intro text in the explorer
show_rst(text[, oname, descriptor, files])	Render restructured text with sphinx and show it
toogle_connect_console()	Disable (or enable) the loading of web pages in www
toogle_url_lock()	Disable (or enable) the loading of web pages in www
update_connect_console(connect)
url_changed(url)	Reimplemented to remove file paths from the url string

Attributes:

bt_url_menus	menu button with different urls
can_document_object	bool determining whether the documentation of an object can be shown or not
can_show_rst	bool determining whether this class can show restructured text
sphinx_thread

Classes:

object_descriptor

Object containing the necessary fields to describe an object given to the help widget.

browse(url)

Reimplemented to add file paths to the url string

bt_url_menus = None

menu button with different urls

can_document_object = True

bool determining whether the documentation of an object can be shown or not

can_show_rst = True

bool determining whether this class can show restructured text

close(self) → bool

describe_object(obj, oname='')

Describe an object using additionaly the object type from the get_objtype() method

Returns:

The descriptor of the object

Return type:

instance of object_descriptor

get_doc(descriptor)

Reimplemented to (potentially) use the features from sphinx.ext.autodoc

get_objtype(obj)

Get the object type of the given object and determine wheter the object is considered a class, a module, a function, method or data

Parameters:

obj (object) –

Returns:

One out of {‘class’, ‘module’, ‘function’, ‘method’, ‘data’}

Return type:

str

header(descriptor, sig)

Format the header and include object name and signature sig

Returns:

The header for the documentation

Return type:

str

is_importable(modname)

Determine whether members of the given module can be documented with sphinx by using the sphinx.util.get_module_source() function

Parameters:

modname (str) – The __name__ attribute of the module to import

Returns:

True if sphinx can import the module

Return type:

bool

object_descriptor

Object containing the necessary fields to describe an object given to the help widget. The descriptor is set up by the describe_object() method and contains an additional objtype attribute

alias of ObjectDescriptor Attributes:

name	Alias for field number 1
obj	Alias for field number 0
objtype	Alias for field number 2

process_docstring(lines, descriptor)

Process the lines with the napoleon sphinx extension

reset_sphinx(value)

Method that is called if the configuration changes

show_help(obj, oname='', files=None)

Render the rst docu for the given object with sphinx and show it

Parameters:

• obj (object) – The object to get the documentation for

• oname (str) – The name to use for the object in the documentation

• files (list of str) – A path to additional files that shall be used to process the docs

show_intro(text='')

Show the intro text in the explorer

Parameters:

s (str) – A string in reStructured Text format to show

show_rst(text, oname='', descriptor=None, files=None)

Render restructured text with sphinx and show it

Parameters:

%(HelpMixin.show_rst.parameters)s –

sphinx_thread = None

toogle_connect_console()

Disable (or enable) the loading of web pages in www

toogle_url_lock()

Disable (or enable) the loading of web pages in www

update_connect_console(connect)

url_changed(url)

Reimplemented to remove file paths from the url string

psyplot_gui.help_explorer.file2html(fname)

psyplot_gui.help_explorer.html2file(url)