When a python function is exposed to Excel with the @xl_func
decorator the docstring of that function is visible in Excel’s function
wizard dialog.
Parameter documentation may also be provided help the user know how to call the function. The most convenient way to add parameter documentation is to add it to the docstring as shown in the following example:
from pyxll import xl_func
@xl_func
def py_round(x, n):
"""
Return a number to a given precision in decimal digits.
:param x: floating point number to round
:param n: number of decimal digits
"""
return round(x, n)
PyXLL automatically detects parameter documentation written in the commonly used Sphinx style shown above, as well as Google style and NumPy style docstrings (new in PyXLL 5.13). Whichever style is used, the parameter descriptions are shown as help strings for the parameters when selected in Excel’s function wizard, and the first line of the docstring is used as the function description.
The arguments and documentation provided are displayed in Excel’s function wizard:
Parameter documentation may also be added by passing a dictionary of parameter names to help strings
to @xl_func as the keyword argument arg_descriptions if it is not desirable to add it to the docstring
for any reason.
New in PyXLL 5.13
Parameters documented in an Args: (or Arguments:/Parameters:/Params:) section are also picked up:
from pyxll import xl_func
@xl_func
def py_round(x, n):
"""Return a number to a given precision in decimal digits.
Args:
x: floating point number to round
n: number of decimal digits
"""
return round(x, n)
New in PyXLL 5.13
Parameters documented in a NumPy-style Parameters section are also picked up:
from pyxll import xl_func
@xl_func
def py_round(x, n):
"""Return a number to a given precision in decimal digits.
Parameters
----------
x : float
floating point number to round
n : int
number of decimal digits
"""
return round(x, n)
A single description can be shared by more than one parameter by listing the comma separated
parameter names on the same line, e.g. x, n : float.
New in PyXLL 5.13
By default reST, Google and NumPy style docstrings are all auto-detected, and PyXLL uses whichever
style it finds first in the docstring. If this detection ever misfires for one of your functions -
for example a reST docstring that also happens to contain a line that looks like a NumPy/Google
section header - the set of styles considered can be restricted using the docstring_styles
setting in the [PYXLL] section of the config file:
[PYXLL]
; Only detect reST/Sphinx style docstrings
docstring_styles = rst
Multiple styles may be listed, separated by commas or on separate lines, e.g. docstring_styles =
rst, numpy. Valid values are rst, google and numpy.
In the Excel function wizard screen there is a “Help on this function” link. You can use this link to reference any URL or CHM (Compiled HTML File) containing your more detailed documentation.
The link to use for the “Help on this function” link is set using the help_topic keyword argument to
the @xl_func decorator.
To set the help topic for a function to a URL pass it as the help_topic` keyword argument to the
@xl_func decorator.
You must use the full URL including the “http://”, “https://”, or “file://” prefix. You can include any query string or anchors that you need in the URL. For example:
from pyxll import xl_func
@xl_func(help_topic="https://www.google.com/search?q=pyxll")
def your_function(...):
....
When you examine this function in the Excel Function Wizard it will now have a link to the URL specified.
Linking to URLs was added in PyXLL 5.1. In earlier versions only linking to CHM files is possible (see below).
CHM, or HTML Help, files are compiled from HPP and HTML files using tools like Microsoft HTML Html (https://docs.microsoft.com/en-us/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads) or other third party tools.
To reference a CHM file for a specific function, when registering the function with :py:deco`xl_func` set the
help_topic kwarg to the absolute path of the .chm file to load, and the section of the file to open as a
numeric help context id in the form “filename.chm!HelpContextID”, e.g. “C:/folder/help.chm!0”.
If you only want to open the chm file, you still have to provide a help context id but it can be 0.
The file path should be an absolute path and must be less than 255 characters long, so you may have to use a windows short path (this is a limitation of Excel).
To add context ids to your chm file you have to add aliases to your hpp file used to make the chm file, e.g.
---- MYHELP.HHP ----
[FILES]
index.html
myfunc1.html
myfunc2.html
myfunc3.html
[ALIAS]
IDH_topic_1 = myfunc1.html
[MAP]
#define IDH_topic_1 1001
-------------------------
Excel doesn’t natively provide IntelliSense or auto-completion for functions provided by add-ins such as PyXLL.
The third party add-in Excel-DNA IntelliSense implements IntelliSense-like auto-completion for Excel add-ins, and this is the recommended way to get auto-completion using PyXLL.
To install the Excel-DNA IntelliSense add-in, download it from https://github.com/Excel-DNA/IntelliSense/releases.
Once you have installed the ExcelDNA-IntelliSense add-in, PyXLL will detect it automatically and start using it to give you auto-completion and in-sheet IntelliSense for your PyXLL functions. The same function documentation as shown in the Excel function wizard is used.
If you need help installing the Excel-DNA IntelliSense add-in then this video will help https://www.youtube.com/watch?v=-BIOzl1igXU.
The Excel-DNA IntelliSense add-in is not part of PyXLL, and is not supported or maintained by PyXLL. It is referenced here for information only. If you need assistance using this add-in you should contact the ExcelDNA team via their github page.
