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
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@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
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@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@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@cgl.ucsf.edu http://plato.cgl.ucsf.edu/mailman/listinfo/chimera-dev
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@cgl.ucsf.edu <mailto:meng@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@embl.de <mailto:kosinski@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@cgl.ucsf.edu <mailto:Chimera-dev@cgl.ucsf.edu> http://plato.cgl.ucsf.edu/mailman/listinfo/chimera-dev
-- Jan Kosinski, PhD Structural and Computational Biology Unit European Molecular Biology Laboratory (EMBL) Meyerhofstrasse 1 69117 Heidelberg Germany
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@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
On Jul 25, 2014, at 10:00 AM, Elaine Meng <meng@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@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@cgl.ucsf.edu http://plato.cgl.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@cgl.ucsf.edu http://plato.cgl.ucsf.edu/mailman/listinfo/chimera-dev
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@embl.de <mailto:kosinski@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@cgl.ucsf.edu <mailto:meng@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@embl.de <mailto:kosinski@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@cgl.ucsf.edu <mailto:Chimera-dev@cgl.ucsf.edu> http://plato.cgl.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@cgl.ucsf.edu <mailto:Chimera-dev@cgl.ucsf.edu> http://plato.cgl.ucsf.edu/mailman/listinfo/chimera-dev
-- Jan Kosinski, PhD Structural and Computational Biology Unit European Molecular Biology Laboratory (EMBL) Meyerhofstrasse 1 69117 Heidelberg Germany
participants (3)
-
Elaine Meng -
Eric Pettersen -
Jan Kosinski