Re: Calling help from a python command line

Subject: Re: Calling help from a python command line
From: Janet Swisher <jmswisher -at- gmail -dot- com>
To: Heather Duggan <hdugganster -at- gmail -dot- com>
Date: Thu, 27 May 2010 11:32:18 -0500

Heather,

Python command-line users are accustomed to accessing help about
Python commands/functions/classes/etc. using the built-in help()
function, which displays information from the item's docstring from
the source code. I strongly recommend using this mechanism rather than
creating a new way of accessing help for Python objects.

Just like for Java and .NET, there are tools for extracting
documentation comments from Python source code and outputting it in a
more readable format. For example, Epydoc produces output very similar
to Javadoc: http://epydoc.sourceforge.net/

If you want to be able to create more traditional documentation that
integrates API reference information into a higher-level structure,
consider using Sphinx with the "autodoc" extension:
http://sphinx.pocoo.org/ It can generate HTML Help source files (which
you can compile to .chm), or generate HTML files that you can import
into your single-sourcing tool. But for this type of information, you
should consider the source code docstrings to be the ultimate "single
source", in order to support the built-in command-line help.

Regards,
Janet Swisher
--
Visit my blog at: http://www.janetswisher.com


On Thu, May 27, 2010 at 10:13 AM, Heather Duggan <hdugganster -at- gmail -dot- com> wrote:
> I seem to have a pent up store of questions. :)
>
> I'm writing help files for commands which can either be accessed from an
> application or from a python command line. We're using .chm files for the
> application help, but we're somewhat stumped about providing help from the
> python command line. Although it's possible to bring up the .chm file from
> the command line, bringing up the *specific* help topic is quite difficult
> (mainly because the search function is broken from the command line, so the
> programmer would have to know an exact topic name or index entry to locate a
> topic.)
>
> Are we going about this the wrong way? We're not at all wed to using .chm
> files. We just want the programmers to be able to get help on a command from
> the python command line, and we want to maintain that command-line help in
> the same way we maintain the rest of our help (i.e., from within a
> single-sourcing authoring tool.)
>
> Thanks,
>
> Heather
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Gain access to everything you need to create and publish documentation,
> manuals, and other information through multiple channels. Choose
> authoring (and import) as well as virtually any output you may need.
> http://www.doctohelp.com/
>
>
>  - Use this space to communicate with TECHWR-L readers -
>   - Contact admin -at- techwr-l -dot- com for more information -
>
>
> ---
> You are currently subscribed to TECHWR-L as JMSwisher -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/jmswisher%40gmail.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwr-l.com/ for more resources and info.
>
> Please move off-topic discussions to the Chat list, at:
> http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gain access to everything you need to create and publish documentation,
manuals, and other information through multiple channels. Choose
authoring (and import) as well as virtually any output you may need.
http://www.doctohelp.com/


- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -


---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


References:
Calling help from a python command line: From: Heather Duggan

Previous by Author: Re: Writing clearly
Next by Author: Re: Fwd: NEWS: MSTP makes the switch: email and website nowhyphenless
Previous by Thread: Calling help from a python command line
Next by Thread: Re: Calling help from a python command line


What this post helpful? Share it with friends and colleagues:


Sponsored Ads