[chimera-dev] how to write documentation for an extension

[Jan Kosinski]

Dear Elaine and Eric,

Thanks a lot! I will probably get an example html page as Elaine 
suggests, edit it and then use Eric's option 3) to bundle the help with 
the extension!

Jan


On 07/25/2014 07:29 PM, Eric Pettersen wrote:
> Hi Jan,
> You probably also want to know how to get your extension to display 
> the help you write.  Unfortunately the "Help" example in the 
> Programmer's Guide hasn't been written.  Here's what you need to know:
> To enable the Help button on a dialog (assuming you are using standard 
> Chimera dialogs from chimera.baseDialog [/i.e./ ModelessDialog or 
> ModalDialog], you set a class variable named "help" to some value 
> (analogous to the class variable "buttons" for specifying what buttons 
> to show).  The possible values are:
>
> 1)  A path.  This is used for extensions whose documentation is 
> bundled with Chimera and therefore probably isn't relevant to you.
> 2)  An URL 
> (/e.g./ "http://myhost.myschool.edu/mylab/me/tool/help.html"). 
>  Chimera will show that URL in a browser when the Help button is clicked.
> 3)  A 2-tuple consisting of a path and a module.  The module can 
> either be your actual extension module object or a string that can be 
> combined with "import" to import your extension.  Your extension 
> should have a "helpdir" folder in it, and the path will be interpreted 
> relative to that folder.  So as an example, ("help.html", "myext") 
> will use "import myext" to import your extension, determine where that 
> is on the file system (using the module's __path__ variable) and then 
> look in its "helpdir" folder to find help.html and show that in a browser.
>
> Let me know if you need more info.
>
> --Eric
>
>                         Eric Pettersen
>                         UCSF Computer Graphics Lab
> http://www.cgl.ucsf.edu
>
> On Jul 25, 2014, at 10:00 AM, Elaine Meng <meng at cgl.ucsf.edu 
> <mailto:meng at cgl.ucsf.edu>> wrote:
>
>> Hi Jan,
>> We do strive for a reasonable amount of consistency in the 
>> documentation that we ship, but there is no official guideline at 
>> this point.  We only have something like that for the extension’s GUI 
>> text:
>> <http://www.rbvi.ucsf.edu/chimera/docs/ProgrammersGuide/frameguidelines.html>
>>
>> One reason is that the tools themselves vary considerably in 
>> complexity and organization, calling for variations on the basic 
>> documentation format.
>>
>> My advice would be to start with the HTML manpage from the most 
>> similar existing tool (click Help button, use browser to save HTML, 
>> then modify, at least if you are comfortable directly text-editing 
>> HTML).  If you are not comfortable working with HTML directly there 
>> are probably other  routes to ultimately generating HTML with a 
>> similar organization and style.
>>
>> We don’t mandate anything specific, however, and the mere fact that 
>> you are actually thinking about documentation is a positive!  Of the 
>> various extensions distributed by others, some have little 
>> documentation, some are documented on websites, and some have 
>> non-HTML documentation (PDF, etc.).  My general impression is that 
>> most don’t include documentation in their download.
>> <http://www.rbvi.ucsf.edu/chimera/plugins/plugins.html>
>>
>> Thanks for asking!
>> Elaine
>> -----
>> Elaine C. Meng, Ph.D.
>> UCSF Computer Graphics Lab (Chimera team) and Babbitt Lab
>> Department of Pharmaceutical Chemistry
>> University of California, San Francisco
>>
>> On Jul 25, 2014, at 6:16 AM, Jan Kosinski <kosinski at embl.de 
>> <mailto:kosinski at embl.de>> wrote:
>>
>>> Hi,
>>> I wrote a custom extension and now I want to create a documentation 
>>> page that upon clicking a Help button opens a web page similarly to 
>>> some other Chimera tools.
>>> Is there any html template, style guide or any important 
>>> instructions I should follow for implementing it?
>>> Thanks in advance,
>>> Jan
>>
>>
>> _______________________________________________
>> Chimera-dev mailing list
>> Chimera-dev at cgl.ucsf.edu <mailto:Chimera-dev at cgl.ucsf.edu>
>> http://www.rbvi.ucsf.edu/mailman/listinfo/chimera-dev
>>
>
>


-- 
Jan Kosinski, PhD
Structural and Computational Biology Unit
European Molecular Biology Laboratory (EMBL)
Meyerhofstrasse 1
69117 Heidelberg
Germany

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://plato.cgl.ucsf.edu/pipermail/chimera-dev/attachments/20140725/a07e5fd4/attachment.html>