Add inheritance diagram to API reference #695

jeremyliweishih · 2020-04-22T20:27:41Z

Fixes #670.

https://codecov.io/gh/FeatureLabs/evalml/compare/master...js_670_inherit
https://app.circleci.com/pipelines/github/FeatureLabs/evalml?branch=js_670_inherit

How it looks locally (note scrolling is enabled for the graph):

…s_670_inherit

jeremyliweishih · 2020-04-22T20:31:02Z

ex:

However when there is more super classes the nodes get small so needs one more fix.

codecov · 2020-04-22T20:34:00Z

Codecov Report

Merging #695 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #695   +/-   ##
=======================================
  Coverage   99.19%   99.19%           
=======================================
  Files         140      140           
  Lines        4952     4952           
=======================================
  Hits         4912     4912           
  Misses         40       40

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 09da1e6...173f217. Read the comment docs.

jeremyliweishih · 2020-04-23T15:56:45Z

@dsherry what I got so far. There should be more enhancements to make it look prettier but I didn't want to spend even more time on this!

dsherry · 2020-04-23T17:08:14Z

@jeremyliweishih I see RTD timed out on building this branch. But maybe that's a RTD problem rather than an issue with your code. I just rekicked it. Will review the code now and then approve once we can see the RTD output.

dsherry · 2020-04-23T19:03:36Z

@jeremyliweishih hmm, that build timed out too. Any idea what's up there? Very strange

dsherry · 2020-04-23T19:06:43Z

@jeremyliweishih one thing to note: the latest run of the build_docs job on this PR took 19min8sec. The latest run on master took 7min31sec. RTD will time out after about 20min of building, so it seems likely that RTD isn't the problem here, it's something in this PR causing an increased build time...

Update: wait a minute, I may be incorrect, looking again.

Yeah, never mind, the version on this branch took 8min25sec. Weird.

dsherry · 2020-04-23T21:41:35Z

@jeremyliweishih I saw the RTD passed for this, so I took a look. Pretty cool!! I'm amazed you got this working, haha. I feel like half the time I try to add something to sphinx I get burned.

I have some questions I'd like to hear your thoughts on:

Are there ever, or will there ever be, situations where the user needs to know the full inheritance structure, and not simply the class one step down?
Bearing that in mind, is this the most clear way to indicate inheritance? Would it be more clear to simply list the base class as I think you suggested originally?
Most of the inheritance plots require scrolling to view. Is there anything we could do to make this clear to users? I'm concerned people will just think the plots are cut off.

jeremyliweishih · 2020-04-23T22:38:30Z

@dsherry I went with this approach in the end mainly due to how many layers of inheritance we have now over the base class approach. The fact that the base class doesn’t link either makes it tedious to understand the inheritance structure we have.

Whether users actually need to understand full inheritance - I think it will be useful for components, pipelines, and objectives since it would be great for them to understand for custom components etc.. But I don’t don’t see a compelling reason for every other thing in the API reference. That’s why initially I thought it would be better to explain full inheritance structure in the walkthroughs as I don’t think it’s that useful to users to understand inheritance in general outside of the custom cases.

Yeah I agree that there’s more to be done to make the diagrams more clear - just wanted to get the review process going since I spent way too much time on it already haha

dsherry · 2020-04-24T18:43:12Z

@jeremyliweishih got it. I think you've convinced me the approach adds value. I do think we could improve the appearance, for instance I wonder if there's a way to have the graphs render vertically rather than horizontally. And I agree we should explain the inheritance and what's expected of users in our docs and not make them turn to the API ref to understand that. But for now, this is a value add and that's great. Nice going :) I'll review the PR.

dsherry · 2020-04-24T18:47:13Z

docs/source/_static/style.css

+img.inheritance { 
+      max-width: none;
+      max-height: 30px;
+}  


Why set specific pixel values for these things as opposed to percentages?

I mean, I guess I understand why the height is fixed at a pixel value. But I wonder if making it slightly more would be helpful. When I scroll to the right on my mac, the scroll bar covers half the image.

The real answer is: I couldn't get it to work with percentages lol. I wanted to use 100% of the div (max-height: 100%) but it never worked for me. Yeah I can bump the height value!

Got it. Weird! That's ok.

dsherry · 2020-04-24T18:48:14Z

docs/source/_templates/class.rst

@@ -2,6 +2,8 @@

 .. currentmodule:: {{ module }}

+.. inheritance-diagram:: {{ objname }}


Which elements use class.rst?

I guess I'm realizing I like that we have estimator.rst / transformer.rst because the names clearly indicate what those files correspond to, but not true with class.rst

@dsherry its just every other class thats not pipeline/estimator/transformer. I made the other .rst files because of class properties.

dsherry · 2020-04-24T18:49:20Z

docs/source/conf.py

@@ -208,6 +210,8 @@
 nbsphinx_execute = 'always'
 nbsphinx_timeout = 600 # sphinx defaults each cell to 30 seconds so we need to override here

+inheritance_graph_attrs = dict(rankdir="LR", size='"1000, 333"',
+                               fontsize=30, labelfontsize=30, ratio='compress', dpi=960)


Interesting. Is there doc on what parameters this module supports?

Yeah! Its just the graphviz parameters. https://www.graphviz.org/doc/info/attrs.html

We can play with them more later to make things prettier 😄

dsherry

I left some questions but it looks good to me!

Can you please verify that adding these graphs hasn't significantly increase our build_docs or RTD build runtime?

jeremyliweishih · 2020-04-24T18:59:11Z

@dsherry on this branch build time was 982s whereas master was 974s so it looks good!

…s_670_inherit

jeremyliweishih added 3 commits April 22, 2020 16:26

Add inheritence diagram

2f810f9

CL

fe4154f

Merge branch 'master' of https://github.com/FeatureLabs/evalml into j…

7b0d406

…s_670_inherit

Remove max-width and add scrolling

6d071d8

jeremyliweishih self-assigned this Apr 23, 2020

jeremyliweishih marked this pull request as ready for review April 23, 2020 15:56

jeremyliweishih requested a review from dsherry April 23, 2020 15:56

Merge branch 'master' into js_670_inherit

ee4f2be

Merge branch 'master' into js_670_inherit

75fe4d0

dsherry reviewed Apr 24, 2020

View reviewed changes

dsherry approved these changes Apr 24, 2020

View reviewed changes

jeremyliweishih added 2 commits April 24, 2020 15:20

Merge branch 'master' of https://github.com/FeatureLabs/evalml into j…

01c027b

…s_670_inherit

Change height

173f217

jeremyliweishih merged commit 360fc60 into master Apr 24, 2020

dsherry mentioned this pull request Apr 24, 2020

Show class inheritance in API reference #670

Closed

dsherry deleted the js_670_inherit branch October 29, 2020 23:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add inheritance diagram to API reference #695

Add inheritance diagram to API reference #695

jeremyliweishih commented Apr 22, 2020 •

edited

Loading

jeremyliweishih commented Apr 22, 2020

codecov bot commented Apr 22, 2020 •

edited

Loading

jeremyliweishih commented Apr 23, 2020

dsherry commented Apr 23, 2020

dsherry commented Apr 23, 2020

dsherry commented Apr 23, 2020 •

edited

Loading

dsherry commented Apr 23, 2020

jeremyliweishih commented Apr 23, 2020

dsherry commented Apr 24, 2020

dsherry Apr 24, 2020

jeremyliweishih Apr 24, 2020 •

edited

Loading

dsherry Apr 24, 2020

dsherry Apr 24, 2020

dsherry Apr 24, 2020

jeremyliweishih Apr 24, 2020

dsherry Apr 24, 2020

dsherry Apr 24, 2020

jeremyliweishih Apr 24, 2020

jeremyliweishih Apr 24, 2020

dsherry Apr 24, 2020

dsherry left a comment

jeremyliweishih commented Apr 24, 2020

		@@ -2,6 +2,8 @@

		.. currentmodule:: {{ module }}

		.. inheritance-diagram:: {{ objname }}

Add inheritance diagram to API reference #695

Add inheritance diagram to API reference #695

Conversation

jeremyliweishih commented Apr 22, 2020 • edited Loading

jeremyliweishih commented Apr 22, 2020

codecov bot commented Apr 22, 2020 • edited Loading

Codecov Report

jeremyliweishih commented Apr 23, 2020

dsherry commented Apr 23, 2020

dsherry commented Apr 23, 2020

dsherry commented Apr 23, 2020 • edited Loading

dsherry commented Apr 23, 2020

jeremyliweishih commented Apr 23, 2020

dsherry commented Apr 24, 2020

Choose a reason for hiding this comment

jeremyliweishih Apr 24, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsherry left a comment

Choose a reason for hiding this comment

jeremyliweishih commented Apr 24, 2020

jeremyliweishih commented Apr 22, 2020 •

edited

Loading

codecov bot commented Apr 22, 2020 •

edited

Loading

dsherry commented Apr 23, 2020 •

edited

Loading

jeremyliweishih Apr 24, 2020 •

edited

Loading