Improve how docstrings for strategies appear/are generated? about axelrod HOT 20 CLOSED

What do you mean by sub header?

from axelrod.

Sorry, I didn't really explain this well.

So at the moment: http://axelrod.readthedocs.org/en/latest/strategies.html shows every strategy's docstring listed out.

That is how an excerpt of how this is done in: https://raw.githubusercontent.com/drvinceknight/Axelrod/master/docs/strategies.rst

Here are some of the basic strategies:
--------------------------------------

.. currentmodule:: axelrod.strategies
.. autoclass:: Alternator
.. autoclass:: Cooperator
.. autoclass:: Defector
.. autoclass:: Random
.. autoclass:: TitForTat

A list of all further (honest) strategies:
------------------------------------------

.. autoclass:: AntiTitForTat
.. autoclass:: Appeaser

So I'm listing each strategy manually, I think I must be missing some sphinx but can't seem to find it: I'd like to just be able to say 'Ok list all the class from axelrod.strategies' here.

Also if possible if they could each have their own subheader (<h4>Alternator</h4> or something like that) that is slightly nicer than what currently appears (class axelrod.strategies.Alternator) that would be cool although perhaps that's not needed... Just trying to think about readability for none coders but maybe that's not important and this isn't exactly 'not readable'. As I've written this I think that that is perhaps really not needed...

from axelrod.

You can use automodule, but then you can't easily break the list into the section you have.

from axelrod.

I tried automodule but without success. Let me try again...

from axelrod.

You could have a Python script generate the rst file, then you can do whatever you want :D

from axelrod.

Yeah I think automodule picks up docstrings for given submodules but not for classes perhaps? Unless I'm doing something wrong: e6d71cc

You could have a Python script generate the rst file, then you can do whatever you want :D

Had thought that... Any idea how that would play with read the docs? I like that it just automatically runs the sphinx makefile... Perhaps I can just tweak that file... I need to look in to it.

Do you think it's worth looking in to or perhaps nicer to just manually list the files so that we 'have control' so to speak? Easy enough to do for each PR... (Thinking aloud here)

from axelrod.

You could have a Python script generate the rst file, then you can do whatever you want :D

This could all just sit in the new manage.py script I keep on talking about...

from axelrod.

Had thought that... Any idea how that would play with read the docs?

As long as the result is the RST file before sphinx starts it's work, it will be independent. See #95.

from axelrod.

Just seen #95... On my list of 'understand awesome voodoo stuff that @langner has written' that's towards the bottom as makefiles still scare the hell out of me...

from axelrod.

As far as I can tell, the make script doesn't run on read the docs. This f4f57be and previous added 5 new strategies that don't seem to appear.

Just re-opening the issue in case you (@langner) had any ideas but I'm happy to close it straight down and simple run make html locally :)

from axelrod.

You might need to force those targets. Otherwise, just run make (no need for make html locally, since you're not interested in getting the actual HTML into the repo).

from axelrod.

Forcing targets in makefiles: https://www.gnu.org/software/make/manual/html_node/Force-Targets.html

from axelrod.

Ok: thanks, will take a look! 👍

from axelrod.

As far as I can tell: running make and even make html does not update the rst file as required (doing so locally)...

At line 26 of the MAKEFILE you have:

strategies.rst: strategies.py
        python $< > $@

Just checking that that > is indeed throwing the output of strategies.py to the rst file (sorry but I have tried on many occasion to get my head around makefiles and I don't think I've succeeded yet...).

from axelrod.

(I expect all of the above is me being an idiot and not understanding the voodoo so please do say so :D)

from axelrod.

The more I think about this the more I think we need to manually curate documentation for each and every strategy, this could actually turn out to be a very nice reference... Would require a docs/strategies/<strategy>.rst file for each one but I think it's worth doing... I'm happy enough to start working my way through it...

from axelrod.

I tend to think that keeping documentation as close to the code as possible is the best, and it can't be closer than a docstring.

from axelrod.

Yeah I agree with that...

I think I'm just unsatisfied with how this all works so I thought that just manually curating the docs for strategies could be a nice way to go...

(I'm just thinking aloud here...)

It is silly though to have the actual docs anywhere else than in the docstring...

Let me work on a branch on this and get back to you... The docs need a bunch of tlc I think, it would be nice to be able to easily find a description of each strategy instead of just that one big list... (still thinking aloud)

from axelrod.

Yeah I agree with that...

I think I'm just unsatisfied with how this all works so I thought that just manually curating the docs for strategies could be a nice way to go...

(I'm just thinking aloud here...)

It is silly though to have the actual docs anywhere else than in the docstring...

Let me work on a branch on this and get back to you... The docs need a bunch of tlc I think, it would be nice to be able to easily find a description of each strategy instead of just that one big list... (still thinking aloud)

I don't understand what final effect you're going for here. Do you simply want each strategy to appear in the table of contents?

Of course, you can also keep additional docs in separate files, if you like. But it makes sense to keep strategy-specific content along with the class.

from axelrod.

I don't understand what final effect you're going for here. Do you simply want each strategy to appear in the table of contents?

I'm not sure I understand either... Probably just mumbling. I think after the merge you just did (#147) we're probably all good. :)

from axelrod.