Even more improvements in plot documentation

[kcrisman]

This is a followup to #9746, to make the docs even better. In addition to the things below, we should put in references like there will now be in matrix_plot (see #9740) to the actual function in the documentation.

---

In scatterplot, there is another one of those 'these are equivalent' things, but they're not separated out. Also, I get code{scatter_plot.options} instead of the actual code. Should it be show() or show()?

In sage.plot.polygon.polygon we have something similar in the examples - somehow you only got some of them. Again with the extra options guy, too. Also, "Extra options will get passed on to show()" should have a hyperlink.

Same with the equivalent in point.py, in both point and points.

In the plot_field.py file, why did you once add the x,y variable declaration and once not? It doesn't really matter to me, but I wonder if there is something I'm missing. Again with the show() or show(), and the equivalent. It's not so important to me with the equivalent showing two things, but I feel like maybe you changed that one place - or maybe not.

In plot.py, ironically, just above the place where you fixed the 1.5/(1+e^(-x)) thing, there are a bunch of plots I didn't separate in my custom ticks patch. My apologies - but there they are! I also still get an error 'ellipsis object not callable' or something in 'add grid lines at specific positions (using lists/tuples)'. There's an ellipsis that got stuck in there still somehow - I think you got a different one of these.

In line.py, after the cool cat there are a couple things as in the previous files - one nonseparated, one equivalent issue/show() issue.

In disk.py, maybe the disk that is parallel to the xy-plane should be plotted, not just its type? Same equiv/show question.

I don't know what happened in density plot, but I think a tick is missing in the DensityPlot documentation - likely my fault? This is in 'Examples'.

In contour plot, the very last example under region_plot should have two plots, but has one. But they are different.

The circles also has the parallel to the xy-plane issue when it comes to giving the type, but not the plot.

CC: @jasongrout @kcrisman @qed777 @boothby

Component: graphics

Issue created by migration from https://trac.sagemath.org/ticket/10032

[jasongrout]

comment:1

Another big improvement would be making all of the plot files start with the user commands, rather than the behind-the-scenes objects.

[kcrisman]

comment:2

Replying to @jasongrout:

Another big improvement would be making all of the plot files start with the user commands, rather than the behind-the-scenes objects.

I don't think this matters at all unless the way our documentation is generated changes, since it's just done alphabetically, right? Or am I missing something?

[jasongrout]

comment:3

Oh, right.  Well, then we should edit the RST files to make it not do alphabetical order, but do the order in the files (I believe it is just an option we can specify somewhere).  Anyway, the point is that it is really confusing right now since the first half of the documentation has no relevance to the end user.

[kcrisman]

comment:4

Replying to @jasongrout:

Oh, right.  Well, then we should edit the RST files to make it not do alphabetical order, but do the order in the files (I believe it is just an option we can specify somewhere).  Anyway, the point is that it is really confusing right now since the first half of the documentation has no relevance to the end user.

Which however would be another ticket, since this would affect lots of things. I think that in general this would be a good change for lots of files - though a big job for someone hand-editing like me.

[jasongrout]

comment:5

Well, I meant a switch just for these files, not a system-wide switch.

[kcrisman]

Description changed:

--- 
+++ 
@@ -3,7 +3,7 @@

In scatterplot, there is another one of those 'these are equivalent' things, but they're not separated out. Also, I get code{scatter_plot.options} instead of the actual code. Should it be show() or show()?

-In sage.plot.polygon.polygon we have something similar in the examples - somehow you only got some of them. Again with the extra options guy, too. +In sage.plot.polygon.polygon we have something similar in the examples - somehow you only got some of them. Again with the extra options guy, too. Also, "Extra options will get passed on to show()" should have a hyperlink.

Same with the equivalent in point.py, in both point and points.

[fchapoton]

Description changed:

--- 
+++ 
@@ -1,6 +1,8 @@
 This is a followup to #9746, to make the docs even better.  In addition to the things below, we should put in references like there will now be in `matrix_plot` (see #9740) to the actual function in the documentation.

-```
+
+---
+
 In scatterplot, there is another one of those 'these are equivalent' things, but they're not separated out. Also, I get code{scatter_plot.options} instead of the actual code. Should it be show() or show()?

 In sage.plot.polygon.polygon we have something similar in the examples - somehow you only got some of them. Again with the extra options guy, too.  Also, "Extra options will get passed on to show()" should have a hyperlink.
@@ -20,4 +22,4 @@
 In contour plot, the very last example under region_plot should have two plots, but has one. But they are different.

 The circles also has the parallel to the xy-plane issue when it comes to giving the type, but not the plot.
-```
+

[548df2ab-93a0-4e53-8343-152970a0b0b2]

comment:12

I am interested in working on this. How do I start?

[kcrisman]

comment:13

I am interested in working on this. How do I start?

Welcome to Sage! Try looking at the developer guide for information. In this case, since it is mainly asking for documentation upgrades, you could create a new branch for this ticket, try fixing the various things indicated, and then once you've checked it builds and looks correct (see e.g. here) then you can post that branch after you commit it. Unfortunately using git is a bit of a learning curve, but luckily most of the work will be just in editing the files and then building documentation to make sure it looks nice.

By the way, this ticket is fairly old, so you may want to check whether everything listed is still a problem. Good luck!

[DaveWitteMorris]

comment:14

Removing the "beginner" tag from old tickets. Some could be returned to beginner-friendly status by adding a comment about what needs to be done. Some others might be easy for an experienced developer to finish.