Plots.jl: Documentation

[tbreloff]

Here's the TODO list... I'll add/change as appropriate:

Concept pages

• [x] Colors, ColorGradients (how and when to use what, what kinds of things are supported, lots of examples, also point to external sources for predefined gradients. see: #139)
• [x] Input data (vectors, matrices, functions, dataframes, tuples, custom objects... talk about all the ways to pass in data and how it gets passed through the pipeline)
• [x] Arguments (vector vs matrix, preprocessing pipeline, magic args, etc)
• [x] Subplots (different ways to build, layout types, linked axes)
• [x] Backends (How to choose... which ones are good at different plot types, some prose about the quality/progress for each package, some side-by-side comparisons of plot examples)
• [ ] Fonts, PlotText, Annotations
• [x] Guides (titles, axis labels/limits/ticks, legend/colorbar)
• [ ] Plot components (path vs line, markers, fills, styles, strokes, shapes, etc) (see #445 for additional ideas)
• [x] Animations
• [x] Recipes (some examples of how to plot custom objects, or to build predefined sequences. discuss both PlotRecipe and _apply_recipe and when you would use either and why they are so much better than making a function that wraps a call to plot)
• [ ] Design decisions (why did I make certain decisions, thoughts on speed, thoughts on different usage patterns, thoughts on why there are many ways to do the same thing, how MLPlots/ExamplePlots fit into the ecosystem)

• [ ] Goals for the future (Make Plots... ???... profit)

  Examples

• [ ] Better/more complex examples covering more functionality

• [ ] Output other than PNG... for example GR could be SVG, Plotly should be HTML

  Tutorials

• [ ] Reorganize notebooks directory in ExamplePlots into tutorials and scratch. (most of them will be scratch currently.) The idea is that these will be "true tutorials" and not just haphazard code. They should combine Plots with some real world workflows and have lots of comments/structure

[pkofod]

I figure this is the correct place to ask. Do you have any plans for a "readthedocs"-type documentation, or do you plan to provide jupyter notebooks as there are now? I think everyone appreciates all the functionality effort that you throw into this project, but sometimes I find it a bit difficult to find example of the listed keywords being used. I'd be happy to help, but I just need to know which direction you're planning to go in.

[tbreloff]

The short answer is yes... I'd like to have a full website that is a rewrite of the readme, the examples, and some short tutorials which cleanly show some basic usage and some "tricky hacks" for power users. The current notebooks were not written as documentation or tutorials... They are mostly just tests and experiments I created while developing. The better place to look is in the examples linked from the readme.

I'm not a web developer, and it seemed easier to just have markdown files when I first started. Any ideas and collaboration for new docs will be very appreciated! My one hope is that all docs can be easily/automatically regenerated without heavyweight dependencies. Maybe I should just use Jekyll and continue to use markdown? Please post any ideas you have... Thanks.

On Feb 2, 2016, at 3:47 AM, Patrick Kofod Mogensen [email protected] wrote:

I figure this is the correct place to ask. Do you have any plans for a "readthedocs"-type documentation, or do you plan to provide jupyter notebooks as there are now? I think everyone appreciates all the functionality effort that you throw into this project, but sometimes I find it a bit difficult to find example of the listed keywords being used. I'd be happy to help, but I just need to know which direction you're planning to go in.

—
Reply to this email directly or view it on GitHub.

[mmagnuski]

readthedocs supports Mkdocs which is very simple - you just create a doc or docs directory where you keep all the .md files and readthedocs does the rest. This is copied from readthedocs documentation:

When you choose _Mkdocs as your Documentation Type_, we will first look for a mkdocs.yml file in your repository. If we don’t find one, we will generate one for you. We will look inside a doc or docs directory first, and then default to the top-level of your documentation.
Then Mkdocs will build any files with an .md extension. If you have a README.md, it will be transformed into an index.md automatically.

[pkofod]

I only mentioned readthedocs because a lot of packages seem to use it, I have no experience with it myself. It does seem to be quite easy to do, though.

[tbreloff]

you just create a doc or docs directory where you keep all the .md files and readthedocs does the rest

This sounds pretty reasonable, but it would take me a little effort to familiarize myself with readthedocs and get it set up for the first time.

If someone is willing to take the first step and initialize the site (without worrying about the content), then a PR would be really awesome. Note: I'd really like to keep the docs within the ExamplePlots.jl repo, not Plots.jl. This is to manage the repo-bloat for Plots. So if you're willing to help get me started, please submit a PR there.

[mmagnuski]

Cool, I think I'll have some time in a few days to submit a PR to ExamplePlots.jl.

[tbreloff]

Great! :+1:

[pkofod]

Cool, once it's working, I'd be happy to read through and improve where possible.

[tbreloff]

I'm starting to work on this... I signed up for readthedocs and connected ExamplePlots.jl. If I get stuck I'll let you know.

[tbreloff]

I've begun work on revamped docs over at https://github.com/tbreloff/ExamplePlots.jl/tree/master/docs. The docs will be hosted at http://plots.readthedocs.org/

This is an official call-to-arms. If anyone wants to take ownership of a topic or section for the docs and write/rewrite, please submit PRs to ExamplePlots, preferably with a new markdown file in the docs directory. I moved most of the existing documentation there as a placeholder. Some of the documentation (most of the examples directory and some of the argument tables) will continue to be auto-generated, so don't worry about those.

Also, if you have any good ideas to add to the list of examples, please post them here and I can integrate them.

Thanks in advance!

[pkofod]

I'll have a look. A quick note: you might want to add a newline in the long "Default" columns of the "Keywords" table

[tbreloff]

I updated the first post in this issue with a roadmap of what I'd like to see for the documentation. If anyone sees something that they feel comfortable taking on, please let me know. It will take me a long time to do these topics justice.

[tbreloff]

Added: http://plots.readthedocs.org/en/latest/backends/

[tbreloff]

WIP: http://plots.readthedocs.org/en/latest/input_data/

[KristofferC]

Batman is too cool!

[pkofod]

I am so tempted to add windows which are randomly lit or not. Good stuff - Plots.jl is probably the only plotting package out there with a Batman plot.

[sglyon]

Maybe the last plot here was inspiration: http://spencerlyon.com/PlotlyJS.jl/examples/line_scatter/

Either way, the batman here goes way beyond my batman there!

[tbreloff]

@spencerlyon2: nice! Maybe I saw that and it entered my subconscious

Any PR that adds windows will be merged!

On Mar 18, 2016, at 1:21 PM, Spencer Lyon [email protected] wrote:

Maybe the last plot here was inspiration: http://spencerlyon.com/PlotlyJS.jl/examples/line_scatter/

Either way, the batman here goes way beyond my batman there!

—
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub

[mmagnuski]

Shouldn't make_batman be built-in? ;)

[tbreloff]

I am so tempted to add windows which are randomly lit or not.

I was looking through this issue again, and I just HAD to do this. Enjoy: https://github.com/tbreloff/ExamplePlots.jl/blob/master/notebooks/batman.ipynb

[tbreloff]

I spent some time on the docs today. http://plots.readthedocs.io/en/latest/

Can everyone please read through and let me know what they think? Anything missing from the TODO list that should really be in the docs?

[Evizero]

very very nice. I like that you got rid of this huge table at the bottom that didn't fit the page and generally was very confusing

[diegozea]

The keyword argument tables, with their synonyms and default values, are missing now :/

[tbreloff]

Ha... the only person in the world that liked them! Until there's better documentation for that, you should get in the habit of looking at https://github.com/tbreloff/Plots.jl/blob/master/src/args.jl

[diegozea]

Ok! :laughing:

[diegozea]

Sorry, but I really miss the old table... You can use the web browser search on supported :/

[joshday]

The search functionality in the docs appears to be broken. I think the issue is with the readthedocs theme, if you're open to changing it.

[tbreloff]

If it just involves changing a setting, I'm certainly open to changing it... what do you suggest the change should be?

[joshday]

OnlineStats is using https://github.com/squidfunk/mkdocs-material (so does the new Documenter.jl package). I like how the search works in it.

[tbreloff]

Thanks for the link Josh, this looks really great! I'll switch as soon as I
have time.

On Saturday, June 18, 2016, Josh Day [email protected] wrote:

OnlineStats is using https://github.com/squidfunk/mkdocs-material (so
does the new Documenter.jl package). I like how the search works in it.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/tbreloff/Plots.jl/issues/83#issuecomment-226944644,
or mute the thread
https://github.com/notifications/unsubscribe/AA492qSrmfSB7Ay8vo4VGwG3_C3tc_BWks5qM_z4gaJpZM4GnI5X
.

[AndrewGibb]

I've found it hard to work out what types of plots are available. A simple list, early in the docs would be very useful. ie

• plot(),
• plot!(),
• heatmap(),
• ...

[ChrisRackauckas]

@AndrewGibb I think you're supposed to really just use plot() and use a keyword argument to specify the series type instead of using different plotting functions. The arguments are in the docs.

[AndrewGibb]

@ChrisRackauckas Thanks for the tip to use plot(). A list of supported plot types would still be useful, however you specify them. Such a list is not in the docs right now.

[ChrisRackauckas]

@AndrewGibb See http://plots.readthedocs.io/en/latest/supported/.

[AndrewGibb]

Thanks @ChrisRackauckas. Apologies for the noise. I was expecting to be able to find this with text search. That visualization is much better.

[tbreloff]

Thanks Andrew. Docs about series types is already on my list, and Chris
pointed you to the best resource for now.

Please note that 'heatmap(...)' is really just a shorthand for 'plot(...,
seriestype = :heatmap)'. I use the shorthands all the time, but only to
save characters... They aren't necessary.

On Monday, June 20, 2016, Andrew Gibb [email protected] wrote:

Thanks @ChrisRackauckas https://github.com/ChrisRackauckas. Apologies
for the noise. I was expecting to be able to find this with text search.
That visualization is much better.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/tbreloff/Plots.jl/issues/83#issuecomment-227111391,
or mute the thread
https://github.com/notifications/unsubscribe/AA492sb8Qo5glVSysu2-OG9ZqLRlihs4ks5qNnG1gaJpZM4GnI5X
.

[tbreloff]

All: I just deployed new documentation using the mkdocs-material theme... the new site will be using the github organization page for JuliaPlots: https://juliaplots.github.io/

It is now hand-built and deployed, so I will no longer be building/hosting through readthedocs. I made some notes inside the yml file if you're curious.

The search functionality seems to be working well... I need to change some formatting, switch those "tip" boxes to something nicer, and do some more cleanup. In the meantime, please check them out and let me know what you think.

[pkofod]

Cool! Looks great, and it's wonderful to be able to search.

[ChrisRackauckas]

Anything still need to be done here? From what I can tell it's all in the docs and the ExamplePlots.

[BioTurboNick]

Figured I'd add: The section of http://docs.juliaplots.org/latest/output/ on Juno says to use an environment variable that no longer works.

[tbenst]

I'm quite accustomed to using matplotlib's object oriented interface, which allows for something like this:

import matplotlib.pyplot as plt
import numpy as np
fig1, ax1 = plt.subplots()
ax1.scatter(np.random.rand(10), np.random.rand(10))
fig2, ax2 = plt.subplots()
ax2.scatter(np.random.rand(10), np.random.rand(10))
ax1.set_title("Fig 1")
ax2.set_title("Fig 2")

I finally figured out how to do this in Plots.jl by guessing that title! might work with an extra arg (super well designed API btw! Could never guess how to do something like this in matplotlib :)

fig1 = scatter(rand(10), rand(10))
fig2 = scatter(rand(10), rand(10))
title!(fig1, "Fig 1")
title!("Fig 2")

Did I miss this in the documentation? Would love to see each function documented!

Edit: Not sure how to do other common things like how do I change legend after plotting?

[daschw]

Contributions to the documentation (https://github.com/JuliaPlots/PlotDocs.jl) are always very welcome!

Edit: Not sure how to do other common things like how do I change legend after plotting?

plot!(fig1, legend = :topleft)

[tbenst]

Thanks @daschw! Have made one small pull request on docs before (https://github.com/JuliaPlots/PlotDocs.jl/pull/116) but haven't gotten any comments, happy to make more contributions going forward as well

[isentropic]

I unpinned https://github.com/JuliaPlots/Plots.jl/issues/2792 and pinned this so that Documentation gets more attention as Plots docs are a little behind current functionality. Perhaps we should make this is a priority issue

[johnnychen94]

Better/more complex examples covering more functionality

FYI, DemoCards.jl is a tool I made for such usage. JuliaImages is a live example using this: https://juliaimages.org/dev/democards/examples/ It is still under development so please comment if you find it useful.