Additional Refactoring of lib.plot [Part 3: other changes] #117

dougthor42 · 2016-07-11T21:55:36Z

Update 2017-09-08

I will not be able to finish all the items in the PR 😢

Per @RobinD42's suggestion, I have made issues for all unfinished items so that someone else can complete them.

This PR now only makes the following changes:

Add an option to draw ticks outside to plot rather than only inside.
Fix instances of wrapper(*args, **kwargs) in built docs
Updates docs
Addes additional "Ticks" demos
Miscellaneous cleanup

All the other items that I wanted to accomplish have their related Issue listed below.

Original PR message

(This PR replaces #112, as I mucked up the git history too much)

This PR will (hopefully) finish off all the changes that I had planned for lib.plot.

It will also include any feedback from Robin and anyone else.

dougthor42 · 2016-07-19T19:34:29Z

@RobinD42

I'm working on the docs for this, trying to fix the docs showing wrapper(*args, **kwargs) for decorated functions and also updating cross references so that they work correctly

Example:

https://wxpython.org/Phoenix/docs/html/wx.lib.plot.plotcanvas.PlotCanvas.html#wx.lib.plot.plotcanvas.PlotCanvas
enableAntiAiasing should be a link

However, I'm having trouble building the docs locally so I can't preview the changes to see if they are working. Should I just assume that the changes are OK and then check them after the buildbot releases a snapshot after the merge? Or do you have another option?

The issues I'm having:

no static assets. Fixed by downloading the most recent docs and copying the _static/images/inheritance folder from them into my working dir.
python build.py etg builds the main docs but nothing from wx.lib.
python build.py sphinx builds the main docs but nothing from wx.lib.
running make html from the docs/sphinx/ director also doesn't built the wx.lib docs.

Am I missing something in my build flow?

Cloned my repo dougthor42/Phoenix.git
Checked out my branch refactor-lib.plot-part3
git submodule update --init
python build.py dox
python build.py etg

RobinD42 · 2016-07-19T22:05:04Z

I was looking at the issue with the docs for the deprecated methods a few days ago. It might be due to the commented-out line self._update_docs() in PendingDeprecation but I didn't test that. BTW, there is a wx.deprecated decorator in the core namespace, (however I see now that it isn't included in the documentation! Shame on me.) It's quite a bit more complex than your PendingDeprecation class as it is able to mark classes and properties as deprecated in addition to functions and methods, so if you want to stick with yours that is okay.

The ReST docs for wx.lib are generated with a separate build command, python build.py wxlib. Since it actually imports the files as it is scanning them you need to be sure that there is a built version of Phoenix on the python path. If it's an installed one rather than a built Phoenix in the workspace, then you may need to do some tricks to make sure it is importing wx.lib from your project workspace instead of the installed wx.lib.

The files in _static/images/inheritance are generated by the dot utility from graphviz. Copying them into place is probably an acceptable workaround if you don't have that installed.

dougthor42 · 2016-07-20T00:24:53Z

Thanks for the info, it allowed me to get the doc builds running locally so I can play around and try to fix things.

Couple of notes for Future Me:

I had to remove the call to demo.run_demo() in __main__.py, as that file would get executed and the demo would pop up. I've gotta come up with another solution for this - perhaps we just don't allow users to call plot as a module (python -m wx.lib.plot)?
Some research [1] suggested adding the call signature as the first line of the docstring on the decorated function. This does not appear to work.
Overriding the call signature in the wx.lib.plot.txt sphinx file is not feasible.
Perhaps switching to a function-based decorator will work...
@functools.wraps(func) decorator should take care of copying __doc__ and __name__.
What about using the decorator package?
Can I use wx.deprecated as a decorator? And would that fix things?
Doc build process:
1. git clean -d
2. Make test changes to live wx in .../site-packages/wx/lib/plot
3. Copy inheritance folder to docs/sphinx/_static/images (Graphvis website is down - can't download)
4. python build.py wxlib
5. python build.py sphinx
6. Check html files.

RobinD42 · 2016-07-20T01:10:12Z

I had to remove the call to demo.run_demo() in main.py, as that file would get executed and the demo would pop up. I've gotta come up with another solution for this - perhaps we just don't allow users to call plot as a module (python -m wx.lib.plot)?

I had already changed that file in the master branch, see 128b28c

Can I use wx.deprecated as a decorator? And would that fix things?

Yes, and I think so. There is also wx.deprecatedMsg for when you want to use it as a decorator and also have a custom message. It's a little awkward, but works. If you see any improvements that can be made there feel free to propose something. The implementations are here: https://github.com/wxWidgets/Phoenix/blob/master/src/core_ex.py#L39

dougthor42 · 2016-07-20T21:09:40Z

Decorated Functions + Sphinx

Doesn't look like any decorators will work. I tried switching to function-based decorators and tried using wx.deprecatedMsg to no avail (the method would not even be added to the docs).

So what I've decided to do is simply add a line to the start of every deprecated function which raises PendingDeprecationWarning instead of decorating them:

def GetFontSizeTitle(self):
    """
    Get Title font size (default is 15 point)

    .. deprecated:: Feb 27, 2016

       Use the :attr:`~wx.lib.plot.plotcanvas.PlotCanvas.fontSizeTitle`
       property instead.
    """
    pendingDeprecation('fontSizeTitle')
    return self.fontSizeTitle

def pendingDeprecation(new_func):
    warn_txt = "`{}` is pending deprecation. Please use `{}` instead."
    _warn(warn_txt.format(inspect.stack()[1][3], new_func),
          PendingDeprecationWarning)

The above renders correctly:

Properties + Sphinx

The other doc question I had was about properties. Right now, properties are rendered by sphinx as:

However, I know that properties can be rendered and that the documentation must be on the getter. I'd like to have the full docstring rendered rather than just two "see X, Y" links which point to the very item that they're under. Is this something that we can change?

A simple docstring on the property would be:

@property
def fontSizeTitle(self):
    """
    The current Title font size in points.

    Use this property to change the size of the plot title. All units are in pts, and the default size is 15pt.

    :getter: Return the size of the plot title.
    :setter: Change the size of the plot title.
    :type:   int or float
    """
    return self._fontSizeTitle

RobinD42 · 2016-07-21T20:16:45Z

Decorated functions: I thought that I had verified wx.deprecated was working as desired, but I may have looked at the wrong example or something. Your workaround is fine with me.

Properties: Andrea's implementation for generating docs for Python code doesn't actually use Sphinx's module scanner tool, etc. It does all the introspection and docstring extraction itself, in order to be able to generate things the same for those modules as it does for the extension modules. So the issue here is simply that the wxlib build command is not doing anything with the properties other than listing and linking the getter and setter methods. It would be great to have it be able to do more than that. If you're interested in working on enhancing that part of the docs generation, the code to tweak is in the Property class in Phoenix/sphinxtools/librarydescription.py.

RobinD42 · 2016-07-23T07:27:37Z

I took another look at it and realized that most of what was needed is already there, so I just pushed a change on master that will output the getter's docstring it is has one.

RobinD42 · 2016-08-10T17:51:11Z

@dougthor42, just FYI I made some minor changes to plot/examples/demo.py on master. See ce00fc0

dougthor42 · 2016-08-10T17:57:41Z

Thanks for the info! Also thanks for making the getter docstring change

And sorry for stalling on this PR. Things have picked back up for me so I haven't had much time recently.

+ added deprecation note to docstring of PolyPoint.setLogScale + Replaced PendingDeprecation decorator with function. + This fixes the documentation having `wrapper(*args, **kwargs)` + Fixed some minor errors due to package conversion + Updated sphinx x-refs to reflect new package structure.

+ Fixed typo in top-side ticks.

+ Changed default ticks to negative (extent out of plot rather an into plot). + Fixed tickLength setter - was setting unused self._tickWitch value + Added tickLengthPrinterScale property + axis values and labels should no longer overlap if tick lengths are negative.

RobinD42 · 2017-05-18T15:41:23Z

When this PR is finished go ahead and remove the wip label and add the needs-review label. Thanks.

dougthor42 · 2017-09-08T00:59:08Z

@RobinD42 It's been over a year, I'm so sorry! 😭 I don't think I'll be able to get around to finishing this.

The without this PR, the plot package should work decently well for some of the simpler cases - after all, the goal was never to replicate Matplotlib or pyqtgraph and the like. In my opinion, the biggest issue with not finishing this particular PR are the docs and deprecation notes.

How do you want to proceed? Some options are:

Merge as-is, ignoring all the proposed improvements in the PR note.
Close this PR and open a new one dedicated to only the docs and deprecation notes.
Close this PR and not merge anything.
Cherry-pick some commits
Other

RobinD42 · 2017-09-08T04:18:58Z

I'll leave it up to you. If the current changes make sense to include we can merge this one, but it would also be nice to not lose track of the remaining todo items in case you or somebody else would like to work on them in the future. Maybe you could create an Issue with those items, links to this series of PRs and maybe a bit of explanation of what you had in mind for the remaining steps if they are not clear.

dougthor42 · 2017-09-08T19:35:10Z

Great idea. I've gone ahead and made separate issues for each item and updated the original PR message accordingly.

The new issues are:

I've removed the WIP from the title and this is ready for review.

RobinD42 · 2017-09-08T20:29:48Z

Thanks!

aKummur · 2018-09-21T10:44:36Z

Does this update allow a plot to have multiple scales like the one in - https://matplotlib.org/gallery/api/two_scales.html ?

dougthor42 · 2018-09-21T16:33:05Z

TBH I don't remember, haha. My gut tells me no, but let me investigate a bit.

dougthor42 · 2018-09-21T17:24:05Z

@aKummur I've confirmed: Sadly the plot package does not support multiple scales.

aKummur · 2018-09-24T09:54:41Z

@dougthor42 Thank you for confirming.

dougthor42 added 7 commits November 28, 2016 14:40

Updated docs for utils.py

d69fb78

Fixed bug with PlotPrintout in plotcanvas.py

98edefd

Miscellaneous cleanup, moved pairwise to utils.py

600cfb4

Refactor if in _Draw(); use parens not \

0f90e02

+ Fixed typo in top-side ticks.

Added bottom-left and all to demo enableTicks

d97731e

RobinD42 added wip enhancement labels Apr 18, 2017

dougthor42 changed the title ~~[WIP] Additional Refactoring of lib.plot [Part 3: other changes]~~ Additional Refactoring of lib.plot [Part 3: other changes] Sep 8, 2017

RobinD42 added needs-review and removed wip labels Sep 8, 2017

RobinD42 merged commit d97731e into wxWidgets:master Sep 9, 2017

dougthor42 deleted the refactor-lib.plot-part3 branch September 12, 2017 23:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Additional Refactoring of lib.plot [Part 3: other changes] #117

Additional Refactoring of lib.plot [Part 3: other changes] #117

dougthor42 commented Jul 11, 2016 •

edited

Loading

dougthor42 commented Jul 19, 2016

RobinD42 commented Jul 19, 2016

dougthor42 commented Jul 20, 2016

RobinD42 commented Jul 20, 2016

dougthor42 commented Jul 20, 2016

RobinD42 commented Jul 21, 2016

RobinD42 commented Jul 23, 2016

RobinD42 commented Aug 10, 2016

dougthor42 commented Aug 10, 2016

RobinD42 commented May 18, 2017

dougthor42 commented Sep 8, 2017

RobinD42 commented Sep 8, 2017

dougthor42 commented Sep 8, 2017

RobinD42 commented Sep 8, 2017 •

edited

Loading

aKummur commented Sep 21, 2018

dougthor42 commented Sep 21, 2018

dougthor42 commented Sep 21, 2018

aKummur commented Sep 24, 2018

Additional Refactoring of lib.plot [Part 3: other changes] #117

Additional Refactoring of lib.plot [Part 3: other changes] #117

Conversation

dougthor42 commented Jul 11, 2016 • edited Loading

Update 2017-09-08

Original PR message

dougthor42 commented Jul 19, 2016

RobinD42 commented Jul 19, 2016

dougthor42 commented Jul 20, 2016

RobinD42 commented Jul 20, 2016

dougthor42 commented Jul 20, 2016

Decorated Functions + Sphinx

Properties + Sphinx

RobinD42 commented Jul 21, 2016

RobinD42 commented Jul 23, 2016

RobinD42 commented Aug 10, 2016

dougthor42 commented Aug 10, 2016

RobinD42 commented May 18, 2017

dougthor42 commented Sep 8, 2017

RobinD42 commented Sep 8, 2017

dougthor42 commented Sep 8, 2017

RobinD42 commented Sep 8, 2017 • edited Loading

aKummur commented Sep 21, 2018

dougthor42 commented Sep 21, 2018

dougthor42 commented Sep 21, 2018

aKummur commented Sep 24, 2018

dougthor42 commented Jul 11, 2016 •

edited

Loading

RobinD42 commented Sep 8, 2017 •

edited

Loading