basic term documentation
Hi,
At [1] you can see the basic sphinx documentation of the terms (scroll down). It took me some time to convert the docstrings, but the result is not bad. The new sources are for the moment at [2], I will push it to the master repo after I get some feedback.
I do not know yet how to hide the common methods of the terms, i.e. do the following split: possibly the extra methods not already defined by Term.
- The Term class documentation with all the common methods
- The Term subclass documentation with only Description, Definition, and
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).
r.
[1] http://rc.github.com/sfepy/developer_guide.html [2] http://github.com/rc/sfepy
Hi Robert,
On Mon, Jan 25, 2010 at 4:40 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Hi,
At [1] you can see the basic sphinx documentation of the terms (scroll down). It took me some time to convert the docstrings, but the result is not bad. The new sources are for the moment at [2], I will push it to the master repo after I get some feedback.
Wow, it looks really nice! Also, it looks like it is easy to add the description (including latex) into docstring of the respective term class.
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! :)
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).
Awesome!
Logan
[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
Logan Sorenson wrote:
Hi Robert,
On Mon, Jan 25, 2010 at 4:40 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Hi,
At [1] you can see the basic sphinx documentation of the terms (scroll down). It took me some time to convert the docstrings, but the result is not bad. The new sources are for the moment at [2], I will push it to the master repo after I get some feedback.
Wow, it looks really nice! Also, it looks like it is easy to add the description (including latex) into docstring of the respective term class.
Yes, for the bulk I have written a small pyparsing-based script, so the conversion was semi-automatic.
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.
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
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
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. :)
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()))
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?
r.
Best, Logan
[1] http://rc.github.com/sfepy/developer_guide.html [2] http://github.com/rc/sfepy
[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
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
Hi,
On Tue, Jan 26, 2010 at 2:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
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].
Ok, it works now. :)
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 :)
I don't know if I was faster...but it's at [6]. :) I also added an example for termsLinElasticity with the full inheritance options just to see what it looks like. I played some more with the autosummary but I think we would have to do a lot of manual maintenance to get the same format as with numpydoc. Maybe we should ask the numpydoc guys if there's a way to selectively turn on and off class method tables.
Thanks! Logan
[1] http://rc.github.com/sfepy/developer_guide.html [2] http://github.com/rc/sfepy
[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 [6] http://github.com/logansorenson/sfepy_doc2
Logan Sorenson wrote:
Hi,
On Tue, Jan 26, 2010 at 2:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
On Mon, Jan 25, 2010 at 12:11 PM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
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 :)
I don't know if I was faster...but it's at [6]. :) I also added an example for termsLinElasticity with the full inheritance options just to see what it looks like. I played some more with the autosummary but I think we would have to do a lot of manual maintenance to get the same format as with numpydoc. Maybe we should ask the numpydoc guys if there's a way to selectively turn on and off class method tables.
Yes, you were :) So, with "numpydoc_show_class_members = False" we would have to write something like
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members: :inherited-members: :show-inheritance:
instead of
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members:
for all the modules/classes where we would wish the full output with class members? It does not look that bad - just two more lines at the module level. But we would have to do it for all the modules, so yes, it might good idea to ask the numpydoc guys if there is an easier way.
As for the renaming, I guess you used some script or bash magic right? :) It worked well in general, but I prepared some traps by having underscores in several module names:
rename from doc/src/sfepy/terms/module_sfepy_terms_terms_hyperelastic_ul.rst rename to doc/src/sfepy/terms/ul.rst
should be rename to doc/src/sfepy/terms/hyperelastic_ul.rst
cheers & thanks! 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 [6] http://github.com/logansorenson/sfepy_doc2
On Wed, Jan 27, 2010 at 3:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Logan Sorenson wrote:
Hi,
On Tue, Jan 26, 2010 at 2:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
On Mon, Jan 25, 2010 at 12:11 PM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
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 :)
I don't know if I was faster...but it's at [6]. :) I also added an example for termsLinElasticity with the full inheritance options just to see what it looks like. I played some more with the autosummary but I think we would have to do a lot of manual maintenance to get the same format as with numpydoc. Maybe we should ask the numpydoc guys if there's a way to selectively turn on and off class method tables.
Yes, you were :) So, with "numpydoc_show_class_members = False" we would have to write something like
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members: :inherited-members: :show-inheritance:
instead of
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members:
for all the modules/classes where we would wish the full output with class members? It does not look that bad - just two more lines at the module level. But we would have to do it for all the modules, so yes, it might good idea to ask the numpydoc guys if there is an easier way.
Yes, although it seems like numpydoc uses some scripting magic to generate the class methods table right after the class docstring so I'm not quite sure how to match their format and ease of use in pure sphinx. I'll ask them if it's possible to add an attribute to control that feature at the per module and per class level.
As for the renaming, I guess you used some script or bash magic right? :) It worked well in general, but I prepared some traps by having underscores in several module names:
rename from doc/src/sfepy/terms/module_sfepy_terms_terms_hyperelastic_ul.rst rename to doc/src/sfepy/terms/ul.rst
should be rename to doc/src/sfepy/terms/hyperelastic_ul.rst
Ah, you caught me here! :) I just used a regex with the rename command, so it looks like I didn't consider this case...do you want me to correct it or have you done so already?
Best, Logan
> [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 [6] http://github.com/logansorenson/sfepy_doc2
Hi,
I submitted issue #53 to the pydocweb project [1].
Logan
Logan Sorenson wrote:
On Wed, Jan 27, 2010 at 3:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Logan Sorenson wrote:
Hi,
Hi Logan,
Logan Sorenson wrote: I don't know if I was faster...but it's at [6]. :) I also added an example for termsLinElasticity with the full inheritance options just to see what it looks like. I played some more with the autosummary but I think we would have to do a lot of manual maintenance to get the same format as with numpydoc. Maybe we should ask the numpydoc guys if
On Tue, Jan 26, 2010 at 2:53 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote: there's a way to selectively turn on and off class method tables. Yes, you were :) So, with "numpydoc_show_class_members = False" we would have to write something like
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members: :inherited-members: :show-inheritance:
instead of
.. automodule:: sfepy.terms.termsLinElasticity :members: :undoc-members:
for all the modules/classes where we would wish the full output with class members? It does not look that bad - just two more lines at the module level. But we would have to do it for all the modules, so yes, it might good idea to ask the numpydoc guys if there is an easier way.
Yes, although it seems like numpydoc uses some scripting magic to generate the class methods table right after the class docstring so I'm not quite sure how to match their format and ease of use in pure sphinx. I'll ask them if it's possible to add an attribute to control that feature at the per module and per class level.
I see, thanks for asking!
As for the renaming, I guess you used some script or bash magic right? :) It worked well in general, but I prepared some traps by having underscores in several module names:
rename from doc/src/sfepy/terms/module_sfepy_terms_terms_hyperelastic_ul.rst rename to doc/src/sfepy/terms/ul.rst
should be rename to doc/src/sfepy/terms/hyperelastic_ul.rst
Ah, you caught me here! :) I just used a regex with the rename command, so it looks like I didn't consider this case...do you want me to correct it or have you done so already?
I have not done it already... feel free to play with the docs as necessary :)
thanks! 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 [6] http://github.com/logansorenson/sfepy_doc2
Hi all,
As for the renaming, I guess you used some script or bash magic right? :) It worked well in general, but I prepared some traps by having underscores in several module names:
rename from doc/src/sfepy/terms/module_sfepy_terms_terms_hyperelastic_ul.rst rename to doc/src/sfepy/terms/ul.rst
should be rename to doc/src/sfepy/terms/hyperelastic_ul.rst
Ah, you caught me here! :) I just used a regex with the rename command, so it looks like I didn't consider this case...do you want me to correct it or have you done so already?
I have not done it already... feel free to play with the docs as necessary :)
Got around to fixing my renaming mistake. Please see [6].
Best, Logan
>>> [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
participants (2)
-
Logan Sorenson -
Robert Cimrman