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

[Jan Kosinski]

Hi Eric,

Yes, I will do it when ready!

Jan

On 07/25/2014 07:50 PM, Eric Pettersen wrote:
> Hi Jan,
> If the extension is of somewhat general interest, you could announce 
> it on chimera-users and we could put a news item on the Chimera home 
> page about it.
>
> --Eric
>
> On Jul 25, 2014, at 10:33 AM, Jan Kosinski <kosinski at embl.de 
> <mailto:kosinski at embl.de>> wrote:
>
>> 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 <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
>> _______________________________________________
>> 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/1b129256/attachment.html>