descriptions for choices of ChoiceParameters

[kecnry]

some choice options aren't entirely intuitive and could use further explanation.

For example 'ck2004' for the atm parameter or different eclipse_methods would benefit from some explanation in the parameter itself rather than needing to look up in the docs.

[aprsa]

if you build a framework for adding descriptions to choice parameters, I am happy to contribute said descriptions. :)

[kecnry]

Awesome, you're hired. I can currently think of 2 ways to do this:

1. ChoiceParameter.choices becomes a dictionary instead of a list. Pretty self-explanatory (I think), but will bloat the ascii output a bit.

b['atm'].choices
{'ck2004': '....', 'blackbody': '....'}

Pros:

• simple to implement
• intuitive
• will be handled by ascii i/o easily

Cons:

• bloats ascii i/o
• a bit ugly to access a single description (b['atm'].choices['ck2004'])

2. A hardcoded "help dictionary" for all of phoebe. This would then also allow for expanded descriptions/details for anything.

phoebe.help('atm')
phoebe.help('ck2004')

and could even be accessed from the Parameter-level

b['atm'].help -> phoebe.help('atm') + phoebe.help('ck2004') + ...

The tricky part about this is that it could get slightly complex if we want to handle any context. If I have my way and the period parameter stays as it is - then do we provide different help strings for period@binary vs period@primary (there are other examples, this is just the most obvious)?

Pros:

• allows long descriptions and references from anything in phoebe, including backend-types, component-types, etc.
• lightweight on the bundle itself (doesn't add to i/o)

Cons:

• lose some flexibility unless we want to implement a twig-like filtering of help strings (which is possible and could easily be passed on from the parameters)

[kecnry]

see the above commit (currently in the "help_framework" branch) and try the following

import phoebe
b = phoebe.default_binary()
b.add_compute()

print phoebe.help('atm')
print phoebe.help('ck2004')

print b['atm@primary'].help

print phoebe.help('period', kind='orbit')
print b['period@binary'].help
print phoebe.help('period')  # this one raises an error

If everyone likes this framework, we can then start populating help messages in this branch (see phoebe.frontend.help) and I can merge back to development once we have decent coverage.

[aprsa]

Two considerations:

(1) I would prefer help to be a method rather than a string, so
phoebe.help(...) would do the printing by itself. I realize that there
would be essentially no difference in the interactive mode except for
typing help() instead of help, but that makes more sense to me rather than
thinking of help as a property.

(2) for multiply defined parameters (such as period), I wouldn't raise an
error, I would recourse through all individual help messages.

My 2 cents.

On October 5, 2016 12:45:39 Kyle Conroy notifications@github.com wrote:

see the above commit (currently in the "help_framework" branch) and try the
following

import phoebe
b = phoebe.default_binary()
b.add_compute()

print phoebe.help('atm')
print phoebe.help('ck2004')

print b['atm@primary'].help

print phoebe.help('period', kind='orbit')
print b['period@binary'].help
print phoebe.help('period')  # this one raises an error

If everyone likes this framework, we can then start populating help
messages in this branch (see phoebe.frontend.help) and I can merge back to
development once we have decent coverage.

You are receiving this because you commented.
Reply to this email directly or view it on GitHub:
#132 (comment)

[kecnry]

(1) I hate printing from phoebe - so instead I changed it (in 535d11b) to call the same pager that python's builtin help function uses (if phoebe is in interactive mode, otherwise it still returns a string). As for parameters - param.help is a property but there is also a param.get_help() method. This was for self-consistency reasons... but now that we don't really return a string anymore, you might be able to convince me to reconsider.

(2) I do state the matches in the error statement. It wouldn't be hard to loop through all the matches though... but let's defer that decision until we see how often it comes up?