idea Document Python Toolboxes (.pyt) in Source Code in ArcGIS Pro Ideas

Add ability to document Python Toolboxes from within pyt file.

JeffJacobson — Thu, 08 Nov 2012 23:13:26 GMT

I would like to be able to add documentation to my Python Toolboxes inside of the pyt file instead of creating the documentation through ArcGIS Desktop "Item Description" process (which generates XML files).

Using the existing method, sometimes if I add a parameter to a Python Toolbox tool, the XML files will be regenerated and I have to redo all of the documentation from scratch. Not cool.

Re: Add ability to document Python Toolboxes from within pyt file.

ShaunWalbridge — Wed, 19 Jun 2013 06:26:47 GMT

Not a direct solution to this issue, but one thing that does help is adding your XML files to a version control system -- I do this with all of the documentation, and this allows you to move between versions easily. The issue of XML regeneration has been fixed, at 10.1SP1 if you add parameters, I can confirm the rest of the help is retained.

Document Python Toolboxes (.pyt) in Source Code

StevenGonzalez1 — Wed, 11 Jul 2018 19:35:36 GMT

I'm working on re-developing some custom ArcMap toolboxes with the new Python Toolbox (.pyt) format.

Overall, the functionality is much better than the standard ArcMap Toolboxes (.tbx) because most of the functionality is embedded in the source code, and not in any binary data as with .tbx files.

That said, is there any way to add the documentation/help for the tool and each parameter within the source code?

Currently, the only way I know how to edit the help files is by editing the Item Description, but feel it would be a greater benefit to include within the .pyt code itself.

Is this possible? Or are there currently any work-arounds to achieve this?

Re: Document Python Toolboxes (.pyt) in Source Code

DuncanHornby — Thu, 12 Jul 2018 15:13:43 GMT

To my knowledge the only way to document parameters for the GUI is to edit the Item Description as you are doing. I would be surprised if this idea is implemented as I guess it would require them to rewrite how the geo-processing framework accesses such information, but you never know?

Re: Document Python Toolboxes (.pyt) in Source Code

StevenGonzalez1 — Thu, 12 Jul 2018 15:20:21 GMT

Thanks Duncan. Admittedly, my understanding of the backend processes (i.e.: the geo-processing framework) is quite limited. Nevertheless, it'd still be a nice feature!

Re: Document Python Toolboxes (.pyt) in Source Code

KoryKramer — Fri, 13 Jul 2018 14:47:16 GMT

It would probably be best to first ask this as a question in a space like Geoprocessing‌ or Python‌ If there isn't a way, then submit as an Idea, or log an enhancement request with technical support.

Re: Document Python Toolboxes (.pyt) in Source Code

NilsRatnaweera1 — Tue, 02 Apr 2019 15:39:28 GMT

I would be very much in favor of this approach. Sphinx and roxygen2 for R have been doing this for year! I've posted this as a question into Python (see here). I came here after writing an SO question on this.

Re: Document Python Toolboxes (.pyt) in Source Code

NilsRatnaweera1 — Thu, 02 May 2019 13:04:41 GMT

I've actually been able to solve this some lines of python code. See my stackoverflow answer: arcpy - Python toolbox documentation from within pyt file - Geographic Information Systems Stack Exchange

Re: Document Python Toolboxes (.pyt) in Source Code

Anonymous User — Mon, 25 May 2020 06:36:33 GMT

To create documentation for Python toolboxes is a pain in the neck. Docstrings/Sphinx could be one possible solution.

Re: Document Python Toolboxes (.pyt) in Source Code

MarkJTurnbull — Mon, 18 Jan 2021 23:36:34 GMT

Would like to see this enhancement implemented soon.

Add Tooltip to Python Toolbox ParameterInfo items

JohnMcGlynn — Tue, 18 Mar 2025 01:51:58 GMT

Currently, the python toolbox parameter tooltips are stored in the Metadata files for the Toolbox. This is wrong. Tooltips are not metadata.
This means that anyone wanting to copy the toolbox must also copy hundreds of .xml files as well. Most people don't know they have to do this, and don't want to anyway.
If the parameter input had an additional line for tooltip, this would remove the problem.

Re: Add Tooltip to Python Toolbox ParameterInfo items

AlfredBaldenweck — Tue, 18 Mar 2025 17:06:11 GMT

Yes, PLEASE.

(I think there may be another Idea out for this out there but I can't find it.)

The XMLs are such a pain to deal with. Copying them over with the toolbox, etc. It'd be one thing if we could place them in another folder or something; for each PYT I make, it gets its own folder, and within that, I sometimes have another folder or two for project-specific modules I've downloaded or for template files, etc.

But having like 10 XMLs floating around is a pain.

I appreciate being able to format the text and stuff for metadata, and I appreciate that the XMLs probably make it easier to switch between metadata styles, but PLEASE let us just set parameter and tool and toolbox metadata as part of each class's properties. I'd gladly trade formatting for that.

Re: Document Python Toolboxes (.pyt) in Source Code

HaydenWelch — Thu, 16 Apr 2026 14:31:39 GMT

Reawakening this thread because this is still a persistent issue. Even just allowing us to specify a file location for the generated XML would be great:

class Tool: def __init__(self) -> None: ... self.xmldoc = f"{Path(__file__).parent / 'xml-doc' / type(self).__name__'}.xml"

As it stands the most irritating thing is that these file NEED to be sidecars which absolutely pollutes any version control system AND makes it difficult to locate the actual toolbox if you have a lot of tools. I have one with ~90 tools and finding the pyt file is nearly impossible thanks to the 90 xml files surrounding it (not an issue with the filebrowser, but when using an IDE I need to disable display of the xml files)