Hi Logan,
Logan Sorenson wrote:
Hi Robert,
On Mon, Jan 25, 2010 at 12:11 PM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
I do not know yet how to hide the common methods of the terms, i.e. do the following split:
- The Term class documentation with all the common methods
- The Term subclass documentation with only Description, Definition, and possibly the extra methods not already defined by Term.
I guess we can just double the .rst files: one set for the full description (1.) and one with the summary (2.). I think for set (2.) we could take :undoc-members: out of the .rst sources and specify manually which members to document, e.g., from [3]:
.. autoclass:: Noodle :members: eat, slurp
where autoclass is automodule in our case. Or we could probably also work on the class level. I haven't had time to test the above yet, but hopefully it works! :) Yes, I think it should be easy. I did this doc version offline, so I could not ask the net. :) If you find time to try it, let me know.
Ah, it looks like I was wrong in my understanding of the situation. It turns out that the tables of class methods were being generated by the sphinx autosummary extension which is run during the autodoc phase when using numpydoc (see [4] and [5]). So the solution is to add "numpydoc_show_class_members = False" in doc/conf.py (see attached - you may need the latest version of numpydoc). This turned off the method tables for me...but now I can't seem to "manually" add them with the ".. autosummary::" directive. Probably need to play with it more. :)
I see. The term docs look definitely better with "numpydoc_show_class_members = False", but I did not commit it yet (waiting for the playing :))
Also, I was having problems with the numpydoc_path in the sfepy config. I made the following change in doc/conf.py to work around it (but I don't know if it's the best solution :) ):
sys.path.append(os.path.abspath(sfepy_config.numpydoc_path()))
changed to:
if sfepy_config.numpydoc_path(): sys.path.append(os.path.abspath(sfepy_config.numpydoc_path()))
Oh, yes, I do not have numpydoc installed system-wide, so I forgot to check for the value None. It should be fixed now at [2].
After this is done, we could happily abandon the old way of generating the sfepy_manual.pdf (which is broken now anyway, as the docstrings changed).
One more thing: I would change a bit (again) the naming of the rst files corresponding to python source files. Since the rst files are now placed in the same directory structure as the sources, is there any reason for having the module paths encoded in the filenames?
Example rename: src/sfepy/terms/module_sfepy_terms_terms_hyperelastic_tl -> src/sfepy/terms/module_term_hyperelastic_tl
Yeah, this is a good idea; I think those names as a holdover from when all the files were in the same directory. :) Would we want to strip the module prefix as well?
+1, let's strip it as well. I will be able to do it at first tomorrow, let me know if you are faster :)
cheers, r.
[1] http://rc.github.com/sfepy/developer_guide.html [2] http://github.com/rc/sfepy [3] http://sphinx.pocoo.org/ext/autodoc.html#dir-automodule [4] http://thread.gmane.org/gmane.comp.python.numeric.general/33797 [5] http://code.google.com/p/pydocweb/issues/detail?id=50&can=1&colspec=ID%20Type%20Status%20Severity%20Milestone%20Owner%20Summary%20Opened