Dictionary mapping player names to classes

[drvinceknight]

On #474 @marcharper wrote:

Just a thought for the future: we might think about having a dictionary mapping player names to classes in the axelrod module for python beginner friendliness (avoiding the need for getattr). Perhaps a solution in search of a problem.

[drvinceknight]

You mentioned this in #683. I wonder if encouraging/adding a 'common names' section to the doc strings would be better? It can then be found by searching the strategy index page?

Just a thought as I thought about this for a bit and wasn't sure how we'd be able to build the dictionary in a way that we'd be sure to not forget to add to it... (Would still be an improvement).

[marcharper]

I'm not sure either -- common names in the docstrings is fine. I'd like there to be a table in the docs that lists each strategy, the common names, and references for each. Then in the contributing docs, we'd have a warning and link to that page.

This is a good problem to have -- the library has really grown!

[drvinceknight]

Yeah for sure: a good problem :)

By a table you mean something more compact than http://axelrod.readthedocs.io/en/latest/reference/all strategies.html?

We could write a Python script that writes that table to rst. We tried before but it's not possible to get read the docs to run that script but we could either just make sure people do it or possibly get Travis to do it and push a commit (maybe to open a PR?)...

[marcharper]

I like that idea. Maybe we can get sphinx to or modify ./test to build the doc. My hope is that there is a single easy-to-find page that someone can ctrl-f a reference title or strategy name (any variant) to find out if it's already in the library.

[drvinceknight]

Yeah sounds good. FWIW, Ctrl-f would work on the current strategy index
page if we included alternate names in the doc strings (which might just be
a simple enough solution?).

On Tue, 9 Aug 2016, 00:50 Marc Harper, [email protected] wrote:

I like that idea. Maybe we can get sphinx to or modify ./test to build
the doc. My hope is that there is a single easy-to-find page that someone
can ctrl-f a reference title or strategy name (any variant) to find out if
its already in the library.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#479 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACCGWhBGwS3j9IAGZG85eBMQjEX4CQWmks5qd8DKgaJpZM4HqMrC
.

[marcharper]

Yeah sounds good. FWIW, Ctrl-f would work on the current strategy index page if we included alternate names in the doc strings (which might just be a simple enough solution?).

For now, sure. I guess I do have a slightly stronger opinion then about how the page looks. For strategies, something like:

LibraryName: "Literature Name 1", Ref [1], "Literature Name 2", Ref [2] ...

For references, another table of the form
Reference: Title, Year, DOI, URL, Strategy A implemented as Library Name A, Strategy B implemented as Library Name B etc.

We could also identify unimplemented and/or desired strategies as listed in #379.

[drvinceknight]

So I'm not 100% sure I see what you mean (but I think I do).

If we're going to use the sphinx autodoc feature for this (which is what we are currently doing) then whatever we have must be in the docstrings of the class. So we we wouldn't be able to have a single big table (or two) with all that information in it. This is all automated by sphinx and as far as I know not 'hackable' (we tried a while back: the best we could do is write a script that wrote the rst file, which we had to remember to run).

How about this: we add to the contribution documentation a 'strict' rst format for the docstrings of strategies and make sure all new strategies follow this (and eventually fix the old ones). So for example for Grudger we would have:

class Grudger(Player):
    """
    Description
    ------------
    A player starts by cooperating however will defect if at any point the opponent has defected.

    Names (Or whatever?)
    -------

    - Grudger: [Ref1_]
    - Grim: [Ref_2]
    """

then (I think) it is possible for sphinx to use those references and have them as a single bibliography. This would also be a nice thing to have as it's own page: bibliography.rst in the reference section! Which could also be used by other tutorials. (The style I'm using there is rst: http://www.sphinx-doc.org/en/stable/rest.html#citations: see "Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #." and "Book or article reference, URL or whatever." <- I think we can write that how we want.)

• The index of strategies page would not be terribly concise (like with a nice single table) but it would have a lot of great information!
• The bibliography.rst would be a great resource with various papers.
• Ctrl-f would work on the index of strategies page
• This would also (eventually) address Add sources for the definitions of strategies #225
• This has the benefit of not adding 'another step' of needing to keep a dictionary up to date (apart from in the PR asking for a paper to be cited if needed). It's all just in the docstring.
• Everything is taken care of by sphinx (and subsequently rtd).

[drvinceknight]

Here are some screenshots showing how this looks:

The bibliography:

It lives in the reference section:

Here's how the citations appear (just written in to the docstrings).

Have put this on the 479 branch with a1dc343 it's pretty simple to implement and I do like the bibliography.rst. There I've just lazily copied the citations but that could have more details if we wanted it. (The references in bibliography.rst can be used anywhere in the documentation.)

(My suggestion of using the header rst format doesn't work as Sphinx doesn't want a header in the docstring for the autodoc to work.)

[marcharper]

You're the docs master @drvinceknight so I'll defer to your best judgment on how to proceed.

[drvinceknight]

Ok so my suggestion would be:

• Add the following to Add sources for the definitions of strategies #225:
  1. creating the bibliography.rst file,
  2. adding instructions about format of docstrings to docs (to include all known names)
• Close this issue as the idea would be that you can ctrl-f on the index of strategies page to find the strategies. Would this be good enough do you reckon?

Then the next step is to work through #225 which would be a big chunk of work :) I think I'd actually enjoy working through that slowly once I'm done with #675, but by all means if someone else wanted to pick that up that would be fine by me.

[drvinceknight]

I've created a bibliography.rst file and added instructions for adding references in #691.

I'm going to close this. I think #225 should be the next step. :)