Docstrings for methods are missing in generated docs - #217

I think the solution is going to have to involve customizing the class.rst template. We might have to change

.. automethod:: __init__

to

{% for item in methods %}
.. automethod:: {{ name }}.{{ item }}
{%- endfor %}

though we may want the method docstrings to be below the autosummary table. I wasn't sure what the best way to specify a custom template directory - @eteq, any suggestions?

For info, the default class.rst template is:

{{ fullname }}
{{ underline }}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: Methods

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Attributes

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

which explains why only __init__ had a docstring.

I've figured out a solution and will attach code shortly

Attached is a fix. A couple of questions for @mdboom and @eteq:

• Did we agree that __init__ should actually be documented in the class docstring? If so, then I can remove init from the table (I have a local copy that does that) and I'll have to reflect AstropyLogger to reflect that
• Is it ok to have attributes come first like I've done it? They got kind of lost if they were after the methods section, and it didn't make much sense to have the summary of methods, attributes, and then the detailed methods.

Also, please check the fix to ensure that it works for you!

I figured out how to automatically include reference files at the top of generated documentation, and have attached it here (see commit message for more details). Let me know if you have any suggestions.

@mdboom - could you test this out with vo and wcs?

@eteq - just to check, any objections to me merging this?

I also agree that it makes sense to remove __init__ from the list - our documentation standard says you document init in the class documentation, not in __init__ itself. I also like the "attributes come first" scheme.

Regarding the references: I'm a little hesitant to force the docs structure to parallel the source structure - that seems rather restrictive and could lead to much confusion. Maybe instead include an additional option to automodsumm that can be used to specify where the references file can be found? @mdboom - would that work for you?

@eteq - agree with the option idea, that would indeed be less restrictive. I do think that the docs should mirror the code structure better than they do at the moment (e.g. we should have docs/io, but I agree that we don't necessarily want to make it compulsory).

@eteq - how do you think we should proceed for this? I agree a :references: attribute would be nice, but I had trouble implementing it in practice as I'm not sure I understand all the subtleties of autosummary.

@astrofrog - I'm not sure if "subtleties" is so much it as "confusingness" :) I haven't had a chance to look at this, as I was very busy last week, but I should be able to either implement this or judge it "unimplementable" by Friday.

Ok - sounds good. I will merge this tonight if you don't get :references: to work, and we can always work on that more in future (the current code is not ideal, but not that bad at the same time - it doesn't require the docs to mirror the package structure, it just requires a reference file be placed in a location that mirrors the package structure if references are desired. If no references are needed, then the docs can be anywhere).

Personally, I think keeping the docs mirroring the source is a minor inconvenience and in some ways a nice thing. Adding the :references: feature adds complication that needs to be maintained. Just my 2c. Maybe I'm still jaded by maintaining the matplotlib plot-directive to work under multiple versions of Sphinx and what a pain that has been ;)

I'm looking at this now, so depending on what timezone "tonight" means, please hold off for just abit on merging, @astrofrog . And I see your point, @mdboom - it depends on just how complicated in ends up having to be.

Alright, I think I could implement the :references: feature, but it's not trivial. Given what @mdboom said, with that in mind, I'm fine with just waiting until later if it becomes more useful, as @astrofrog suggests.

Also, @astrofrog , there's a PR astrofrog#12 that addresses the template location issue (and #243 as a bonus).

Ok, I merged in your PR and have also removed __init__ from the method list as we discussed before, so I'll merge this in.

@eteq - for some reason, the docs on readthedocs don't reflect the template change - any ideas?

@eteq - I think it's a cache problem, I added the logging docs back (they had disappeared due to the move) and those are ok, but other generated pages are not. I'll see if we can make a clean build.

Try sending a POST to http://readthedocs.org/wipe/astropy/ - that clears the build environment and has fixed similar issues before

Oops, I meant http://readthedocs.org/wipe/astropy/latest

Ok, it seems to be fixed now - I had opened an issue with readthedocs, so maybe they did just that. Good to know for future!

Actually, I did it just now because I discovered you can just go to that address with a regular webbrowser and click a button to do the wipe. If you ever need to do this in the future, note that you have to manually trigger a new build after the wipe.

Ok, awesome! I'll close the issue with readthedocs.