topic Re: Create a Help file for a new geoprocessing tool in Python Questions

Create a Help file for a new geoprocessing tool

ehallisey — Thu, 29 Mar 2012 13:37:32 GMT

I'm trying to create a simple Help file in ArcGIS 10 for a new geoprocessing tool created by a developer with whom I work. Here's all I can find from Esri on this:

There are many sources of information on creating and compiling HTML help or .chm files. A good starting point is the "Microsoft HTML Help 1.4 SDK" topic available from the Microsoft library (http://msdn.microsoft.com). In the library, you'll also find information on creating and compiling .chm files listed under Visual Tools and Languages, HTML Help.?

I'm not a developer and I don't relish the idea of having to download, install, and learn how to use another software package just to create a few help pages. Also, I can't find a "Microsoft HTML Help 1.4 SDK" topic from the link Esri provides and the most recent version of HTML Help, downloadable from Microsoft, seems to be from 2003.

Does anyone know of a workaround? Has anyone worked with HTML Help? Any quick start tutorials? Any suggestions?

Thanks!
Elaine

Message was edited by: Curtis Price (reformatting to Geonet)

Re: Create a Help file for a new geoprocessing tool

curtvprice — Thu, 29 Mar 2012 14:01:54 GMT

Is this a custom tool (.NET) or a script tool?

If it's a script tool, documentation is added by right clicking the tool, selecting Item Description and editing the metadata.

For GP tools built using .NET (called a "custom geoprocessing tool" instead of the more common "script tool" built in Python or another scripting language) you do indeed need to create a .chm file and set the tools HelpFile property to point to it. Although the Microsoft Windows HTML Help SDK is still supported (in Windows 7), it's very difficult to use. This is usually handled using third-party help authoring applications (Esri uses one obviously) that create documentation in various formats (including .chm) from a single source. Robohelp is one of the most popular ones out there.

Re: Create a Help file for a new geoprocessing tool

Zeke — Thu, 29 Mar 2012 14:06:50 GMT

I don't know about all the Microsoft html help, but you can add help to the tool itself. Click on the tool in ArcCatalog, click on the Description tab in the large pane, click Edit, and you can add the help text that displays when you run the tool, or you can see it in the Description tab. It will also show up in the Catalog tab in ArcMap and Arc Toolbox by right clicking and selecting either Help or Item Description. Help just displays the help while Item Description allows editing it.

Re: Create a Help file for a new geoprocessing tool

KimOllivier — Fri, 30 Mar 2012 00:06:39 GMT

You need to install a help authoring tool.
These are easy to use, and will compile the help file in CHM and web help formats, plus my chosen one will also output a Word Document or PDF. I used to use HelpBreeze, but it has fallen behind so I switched to HelpSmith which could import all my old help files. HelpBreeze is cheaper but a security upgrade in Windows prevents saving edits and HB have not fixed it.

HelpSmith cost $200 but since I purchased it I now write a proper integrated help file for every project I am involved with. I now start early with a specification and mockup of the screens right into the help file and then use it to keep track of specification changes. I find it easy to link the geoprocessing tools to topics in the help files.

The new default help editing tool at 10.x are now so difficult to use I now just get on with a HelpSmith project at the start. It has many other benefits, the files can be stand-alone, incorporated in other web resources and are easy to maintain in a single document, whereas the ArcGIS help is separate for each tool.

www.helpsmith.com

Re: Create a Help file for a new geoprocessing tool

ehallisey — Mon, 02 Apr 2012 12:58:54 GMT

Thanks Greg - this simple solution does exactly what I need. I'm surprised Esri doesn't have a description of this when you search Help on "create help."

Re: Create a Help file for a new geoprocessing tool

KevinHibma — Mon, 02 Apr 2012 14:43:36 GMT

I guess not for "create help"
But "document tool" finds it.

http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//001500000014000000.htm

"Help" is such a generic word through the whole help/doc system 🙂

Re: Create a Help file for a new geoprocessing tool

Jasonvan_Warmerdam — Mon, 02 Apr 2012 16:28:20 GMT

I guess not for "create help"
But "document tool" finds it.

http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//001500000014000000.htm

"Help" is such a generic word through the whole help/doc system 🙂

Khibma,

I've been trying to add help to some of the scripts I've created at work using the methodology laid out in the above link, "documenting tools and toolboxes." After I get done editing in the item description window and then click on the tool I get a Script Error and ArcMap proceeds to crash :(. This error happens when editing the script in the catalog menu, I have also tried editing tool item descriptions from ArcCatalog and remember getting script errors there as well. I'm just not sure at what process the program crashes out. Just wanted to know if this was on my end or if other people are having this problem.

I was also curious about how to add pictures to the tool's side-panel help like some of the Arc Tools have in their help descriptions.

[ATTACH=CONFIG]13185[/ATTACH]

Re: Create a Help file for a new geoprocessing tool

curtvprice — Mon, 02 Apr 2012 16:43:25 GMT

After I get done editing in the item description window and then click on the tool I get a Script Error and ArcMap proceeds to crash :(.

I have not seen this script error crash myself. The first thing I suggest when people get unexpected crashes like this is to reset your application profile. (I do this on every update and service pack.)

I was also curious about how to add pictures to the item description like some of the Arc Tools have in their help descriptions.

Since the Arc 10 script documentation is using the same metadata schema as metadata elsewhere in the system, this is no longer supported (it was in 9.3). They may eventually allow this by adding bitmap attachments to the metadata model but it would be kind of kludgy.

Another option to consider is to create a web site and have your help link to it. This has the advantage of providing users the most current documentation, since you can update the web site at any time after they download your tool.

Re: Create a Help file for a new geoprocessing tool

KevinHibma — Mon, 02 Apr 2012 18:05:10 GMT

I've searched our internal database and asked a couple people - we dont have any known issues logged for a crash in this regards.

Can you confirm you're using 10.0?
Also, is the crash consistently reproducible? If it is, can you write out the steps you do where it crashes?
If we can reproduce the crash, we can fix it (and of course want to fix it)

Re: Create a Help file for a new geoprocessing tool

Jasonvan_Warmerdam — Tue, 17 Apr 2012 17:29:28 GMT

I've searched our internal database and asked a couple people - we dont have any known issues logged for a crash in this regards.

Can you confirm you're using 10.0?
Also, is the crash consistently reproducible? If it is, can you write out the steps you do where it crashes?
If we can reproduce the crash, we can fix it (and of course want to fix it)

I'm using ArcGIS 10 service pack 3:
1. Open ArcMap
2. From within ArcToolbox navigate to the script you would like to edit
3. Right click on the tool and Select Item Description
4. Do something (I've found you can make it crash just by opening Item Description).
5. Close Item Description
6. Click on the script, or any script and watch the program crash out :(..... Script Error

I can create Item descriptions for my geoprocessing tools from within ArcCatalog though.

Re: Create a Help file for a new geoprocessing tool

KevinHibma — Tue, 17 Apr 2012 20:44:36 GMT

Thanks for the follow up.
I cannot reproduce the problem as you describe on my 10.0 spX machine.
Just a guess, if you re-name your profile and re-start ArcMap, does it still happen?

Navigate to:
C:\Users\<user>\AppData\Roaming\esri
Rename the Desktop10.0 folder to something else
Open ArcMap, and try your steps.

When you're done if you can re-name the folder back if you want to regain the settings of ArcMap

Re: Create a Help file for a new geoprocessing tool

GerryGabrisch — Thu, 26 Apr 2012 20:09:40 GMT

FYI, if you open your tools parameters in ArcToolbox and go to the General tab, you can enter valid HTML code in the Description box which is a simple way to create nice looking help.

Re: Create a Help file for a new geoprocessing tool

JonathanCusick — Fri, 27 Jun 2014 13:27:09 GMT

Hey Curtis,

I created a script tool with Python and am trying to add documentation to it. I was able to enter a general description of the tool that appears in the tool help when it is first opened, but when I click on one of the specific input parameters, the description in the tool help is blank and I can't figure out where to edit it. I've also tried right clicking on the script tool itself in ArcCatalog (10.2.1) but do not get an "Item Description" button. Any suggestions?

Thanks!
Jon

[ATTACH=CONFIG]34950[/ATTACH][ATTACH=CONFIG]34951[/ATTACH]

Is this a custom tool (.NET) or a script tool?

If it's a script tool, documentation is added by right clicking the tool, selecting Item Description and editing the metadata.

For GP tools built using .NET (called a "custom geoprocessing tool" instead of the more common "script tool" built in Python or another scripting language) you do indeed need to create a .chm file and set the tools HelpFile property to point to it. Although the Microsoft Windows HTML Help SDK is still supported (in Windows 7), it's very difficult to use. This is usually handled using third-party help authoring applications (Esri uses one obviously) that create documentation in various formats (including .chm) from a single source. Robohelp is one of the most popular ones out there.

Re: Create a Help file for a new geoprocessing tool

curtvprice — Fri, 27 Jun 2014 19:28:51 GMT

The right click thing is in ArcMap. In ArcCatalog, select the script, click the description button and click edit.

When editing script tools, it's best to have your Customize/Options/Metadata set to "Item Description" style.

Re: Create a Help file for a new geoprocessing tool

JonathanCusick — Wed, 02 Jul 2014 18:28:43 GMT

Thank you!

The right click thing is in ArcMap. In ArcCatalog, select the script, click the description button and click edit.

When editing script tools, it's best to have your Customize/Options/Metadata set to "Item Description" style.

Re: Create a Help file for a new geoprocessing tool

TedKowal — Tue, 13 Jan 2015 15:38:52 GMT

There are some alternatives .... I will not say they are easier or better only cheaper if you are on a tight budget some of these are free or opensource.... At some point in time I have used all of the below.... ( I currently use Robohelp since now I have a software budget )

Sandcastle -- http://shfb.codeplex.com/

Help & Manual - The most popular help authoring and documentation tool

HTML Help Workshop and Documentation from Official Microsoft Download Center

KEL CHM Creator v.1.4.0.0 | Dumah's blog

HelpScribble - Complete Help Authoring Tool - WinHelp hlp, HTML Help chm, Printed Manual and Web Help

HelpNDoc | HTML help authoring tool, Word, PDF and eBook documentation generator

Hope this helps for those on a tight budget......

Re: Create a Help file for a new geoprocessing tool

GerryGabrisch — Thu, 15 Jan 2015 15:48:14 GMT

And you can use HTML tags to format the item description for a nicer looking tool.

Re: Create a Help file for a new geoprocessing tool

tinaYang — Wed, 02 Sep 2015 15:04:15 GMT

I have developed a script tool. Now I will edit the documentation by clicking the item description. However after I press the edit button, only generic information are available for editing. Some specific parameters (such as usage, input parameters ) are not shown up for editing. Anyone has suggestions on how to edit these specific parameters? thanks

Re: Create a Help file for a new geoprocessing tool

ShaunWalbridge — Tue, 08 Sep 2015 17:41:58 GMT

Can you post a screenshot of what you're seeing when trying to modify the documentation of a tool?

Re: Create a Help file for a new geoprocessing tool

curtvprice — Fri, 25 Sep 2015 23:50:04 GMT

Tina,

Make sure your app options, metadata tab are set to Item Description before trying to edit tool documentation. This will turn on a more appropriate stylesheet.