Document Python Toolboxes (.pyt) in Source Code

07-11-2018 12:35 PM
Status: Open
Labels (1)
New Contributor III

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?

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.
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.

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? 


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! 


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.


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.


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 Exc... 

by Anonymous User

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


Would like to see this enhancement implemented soon.