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. They will appear in the function wizard as help strings for the parameters when selected. The first line will be 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.
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.
Note
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.
Note
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.
