Three more plot_directive configuration options

[abakan-zz]

Hello,

I have added three new configuration options to Sphinx extension plot_directive. The added code must not change any behaviour of the extension, but will add more flexibility.

• plot_apply_rcparams : allows appyling rcParams when context is used
• plot_working_directory : allows running plot directive codes in any directory
• plot_template : allows customization of template used for generating restructured text

This is how I use these new options to customize plot_directive when documenting a project of mine.

plot_formats = [('png', 80), ('pdf', 80)]
plot_pre_code = """import numpy as np
from prody import *
from matplotlib import pyplot as plt
"""
plot_working_directory = os.path.join(os.getcwd(), 'doctest')
plot_template = """
{{ source_code }}

{{ only_html }}


   {% for img in images %}
   .. figure:: {{ build_dir }}/{{ img.basename }}.png
      {%- for option in options %}
      {{ option }}
      {% endfor %}

      {{ caption }}
   {% endfor %}

{{ only_latex }}

   {% for img in images %}
   .. image:: {{ build_dir }}/{{ img.basename }}.pdf
   {% endfor %}

"""
plot_rcparams = {'font.size': 10,
                 'xtick.labelsize': 'small',
                 'ytick.labelsize': 'small',
                 'figure.figsize': [5., 4.],}
plot_apply_rcparams = True

[WeatherGod]

Shouldn't this be defaulting to False, rather than None? Booleans are much more clear in their intent than Nones.

[WeatherGod]

Sorry, got confused. I see that it is supposed to be a string

[WeatherGod]

Besides the points I made, I have no problem with this PR. If anything, the doc strings could be a little bit more descriptive to help illustrate the possibilities, but they are largely sufficient at this point. Let me know when you address my comments.

[abakan-zz]

Thanks for your comments. I have addressed all of them.

I have a question about handling potential problems with the configuration option plot_working_directory. If user sets an invalid path, an OSError is raised and Sphinx terminates. If I catch this exception and throw a PlotError instead, Sphinx keeps evaluating plot directives, but the working directory is not changed and when needed data files are not accessed, causing other problems.

I would favor throwing OSError with a message saying that "plot_working_directory is not a valid path", which may be helpful for troubleshooting.

How do you think this should be handled? Thanks again for your prompt attention.

[WeatherGod]

Good question. I agree with the latter approach.

[abakan-zz]

I am handling potential OSError and TypeError in the updated module. Sphinx output for different exception types are below. Any other suggestions? Thank you.

Invalid path type:

Exception occurred:
  File "/home/abakan/Code/ProDy/prody/plot_directive.py", line 476, in run_code
    raise TypeError(str(err) + '\n`plot_working_directory` option in '
TypeError: coercing to Unicode: need string or buffer, int found
`plot_working_directory` option in Sphinx configuration file must be a string or None
The full traceback has been saved in /tmp/sphinx-err-7DZjB6.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

Invalid type path:

Exception occurred:
  File "/home/abakan/Code/ProDy/prody/plot_directive.py", line 472, in run_code
    raise OSError(str(err) + '\n`plot_working_directory` option in'
OSError: [Errno 2] No such file or directory: '/home/abakan/Code/ProDy/doc/doctests'
`plot_working_directory` option inSphinx configuration file must be a valid directory path
The full traceback has been saved in /tmp/sphinx-err-OBTBwg.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

[WeatherGod]

Looks good to me. Thanks for your work. Merging...