update index, tutorial, and manual #1173

bjarthur · 2018-07-08T11:26:21Z

made the index more succinct.
the plot signatures in the tutorial were way out of date.
moved the Array API from the manual to the tutorial
added subplot_grid to the manual.
use more interesting examples throughout
remove the reference to D3 in the backends section (no longer exists, right?)
make docstrings for Theme out of the text in the themes section.

once done it should be straightforward to convert the existing docs into a jupyter notebook for a video with @xorJane

codecov-io · 2018-07-09T11:56:03Z

Codecov Report

❗ No coverage uploaded for pull request base (master@3071ad6). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #1173   +/-   ##
=========================================
  Coverage          ?   87.32%           
=========================================
  Files             ?       34           
  Lines             ?     4080           
  Branches          ?        0           
=========================================
  Hits              ?     3563           
  Misses            ?      517           
  Partials          ?        0

Impacted Files	Coverage Δ
src/guide.jl	`86.21% <ø> (ø)`
src/guide/keys.jl	`92.4% <ø> (ø)`
src/varset.jl	`100% <ø> (ø)`
src/Gadfly.jl	`79.04% <ø> (ø)`
src/theme.jl	`67.3% <ø> (ø)`

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 3071ad6...f27b11a. Read the comment docs.

bjarthur · 2018-07-26T21:28:24Z

this is ready to merge i think. could someone please review?

in particular, please let me know if the tutorial and manual are now amenable to a simple translation into a jupyter notebook for a video tutorial. i tried to work them towards this direction.

one thing i need to fix is the strange "Plot(...)Plot(...)" in the output when building the docs.

i'll be completely offline from august 2-15th, and plan on digging into 0.7 when i get back.

xorJane

I looked at the tutorial and manual changes. The manual looks more clear with these changes and the tutorial looks great. It should be easy to convert these to notebooks for a video tutorial. :)

xorJane · 2018-07-26T21:47:01Z

docs/src/tutorial.md

-mapping "aesthetics" to columns in the data frame, and this is followed by some
-number of elements, which are the nouns and verbs, so to speak, that form the
+The first argument is the data to be plotted, the keyword arguments at the end
+map "aesthetics" to columns in the data frame, and everything in between is some


This sentence was a little long/hard for me to read on a first pass. Perhaps consider breaking it up as

The first argument is the data to be plotted and the keyword arguments at the end map "aesthetics" to columns in the data frame. All input arguments between data and mapping are some number of "elements", which are the nouns and verbs, so to speak, that form the grammar.

I second this.

tlnagy

This is a great update overall, I only have a couple minor comments.

tlnagy · 2018-07-27T00:25:47Z

docs/src/man/themes.md

-## Examples
+The constructor for `Theme` takes zero or more keyword arguments each of which
+overrides the default value of the corresponding field.  See the Theme entry in
+the [Library](@ref Gadfly) for a full list of keywords.


Maybe have a direct link to Theme's docstring here?

tlnagy · 2018-07-27T00:27:28Z

docs/src/tutorial.md

-mapping "aesthetics" to columns in the data frame, and this is followed by some
-number of elements, which are the nouns and verbs, so to speak, that form the
+The first argument is the data to be plotted, the keyword arguments at the end
+map "aesthetics" to columns in the data frame, and everything in between is some


I second this.

tlnagy · 2018-07-27T00:29:36Z

docs/src/tutorial.md

-```
+
+Note that there is also no need to specify `Geom.point`, as that will be
+supplied automatically if no other geometries are given.


Should we be recommending this behavior? IMO it's better to be explicit about what we're plotting.

if we ever removed Geom.point as a default, then we should make this change. otherwise best to document it i think.

Perhaps we could say something along the lines of:

In cases where no explicit geometry is provided, the plot will use Geom.point by default.

This way, it doesn't sound like we're recommending this behavior, but it does document that this is the default.

tlnagy · 2018-07-27T00:30:08Z

docs/src/tutorial.md

+plot(elements::Element...; mapping...)
+```
+
+Here, the keyword arguments directly supply the data to be ploted,


ploted

Should be plotted.

instead of using them to indicate which columns of a DataFrame to use.

Not sure if this adds anything

tlnagy · 2018-07-27T00:37:28Z

docs/src/tutorial.md

+```
+
+Note that with the Array interface, extra elements must be included to specify the
+axis labels, whereas with a DataFrame they default to the column names.


Note that with the Array interface, extra elements must be included to specify the axis labels, whereas with a DataFrame they default to the column names.

What about:

Note that with the Array interface, the axis labels cannot be directly inferred so include explicit calls to Guide.xlabel etc to specify the axis names.

tlnagy · 2018-07-27T00:40:17Z

src/theme.jl

+
+"""
+$(FIELDS)
+"""


🎉

This will make keeping the docs in sync much easier and avoid issues like #852

tlnagy · 2018-07-27T00:41:16Z

src/theme.jl

+
+"""
+$(FIELDS)
+"""
 @varset Theme begin
    # If the color aesthetic is not mapped to anything, this is the color that
    # is used.


I feel like the comments are unnecessary with the docstring update and we should remove them.

tlnagy · 2018-07-27T00:42:28Z

src/varset.jl

+end
+"doc struct"
+@foo(Foo, "doc var", x, Int)
+=#


Where is this macro used?

bjarthur · 2018-07-30T11:47:54Z

thanks for the reviews! will merge once CI passes.

bjarthur · 2018-07-31T11:21:10Z

merged! @xorJane what are the next steps to create a video tutorial?

xorJane · 2018-08-20T23:11:52Z

@bjarthur I'm so sorry I missed this! Now that you already have content, the steps are just to schedule the tutorial, show you how to stream/check your internet connection prior to that date, and then stream/talk through the tutorial on the scheduled date. If you have a sense of what dates might be good for you, let me know and we can put up announcements on julialang.org/learning as well as discourse, etc.

Do you have access to a stable ethernet connection? Upload speeds over wifi have been pretty consistently bad/unreliable for previous tutorials, and then we see a lot of buffering and resulting frustration. :)

xorJane · 2018-08-20T23:12:09Z

And thank you again!!

bjarthur force-pushed the bja/docs branch from d54c3c2 to 663015d Compare July 9, 2018 11:56

bjarthur force-pushed the bja/docs branch from e72e359 to 601e3be Compare July 15, 2018 20:15

bjarthur changed the title ~~WIP: update index, tutorial, and manual~~ update index, tutorial, and manual Jul 20, 2018

bjarthur mentioned this pull request Jul 20, 2018

Use DocStringExtensions in Gadfly #1161

Closed

bjarthur force-pushed the bja/docs branch 2 times, most recently from 9479107 to f213dce Compare July 26, 2018 21:23

bjarthur force-pushed the bja/docs branch from f213dce to 05687ec Compare July 26, 2018 21:38

bjarthur mentioned this pull request Jul 26, 2018

too much white space JuliaDocs/DocStringExtensions.jl#63

Closed

xorJane approved these changes Jul 26, 2018

View reviewed changes

tlnagy reviewed Jul 27, 2018

View reviewed changes

bjarthur force-pushed the bja/docs branch 4 times, most recently from 88d35de to 7178ec7 Compare July 30, 2018 11:36

bjarthur force-pushed the bja/docs branch 2 times, most recently from 2449844 to f27b11a Compare July 31, 2018 11:14

bjarthur added 5 commits July 31, 2018 07:14

update tutorial with current plot signatures, and doc Array interface

9dd12df

remove duplicate docs from man/plotting, and add more examples

3fdae8d

add faceting docs to manual; use better examples

c060b88

update backend docs

3b02d77

add docstrings to Theme

f27b11a

bjarthur merged commit fcf7596 into GiovineItalia:master Jul 31, 2018

bjarthur deleted the bja/docs branch July 31, 2018 11:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update index, tutorial, and manual #1173

update index, tutorial, and manual #1173

bjarthur commented Jul 8, 2018 •

edited

Loading

codecov-io commented Jul 9, 2018 •

edited

Loading

bjarthur commented Jul 26, 2018

xorJane left a comment

xorJane Jul 26, 2018

tlnagy Jul 27, 2018

tlnagy left a comment

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

bjarthur Jul 30, 2018

tlnagy Jul 30, 2018

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

tlnagy Jul 27, 2018

bjarthur commented Jul 30, 2018

bjarthur commented Jul 31, 2018

xorJane commented Aug 20, 2018

xorJane commented Aug 20, 2018

update index, tutorial, and manual #1173

update index, tutorial, and manual #1173

Conversation

bjarthur commented Jul 8, 2018 • edited Loading

codecov-io commented Jul 9, 2018 • edited Loading

Codecov Report

bjarthur commented Jul 26, 2018

xorJane left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tlnagy left a 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bjarthur commented Jul 30, 2018

bjarthur commented Jul 31, 2018

xorJane commented Aug 20, 2018

xorJane commented Aug 20, 2018

bjarthur commented Jul 8, 2018 •

edited

Loading

codecov-io commented Jul 9, 2018 •

edited

Loading