Comments (14)
These are good suggestions IMHO. See also JuliaPlots/Plots.jl#676 bit unsure whether this JuliaPlots/Plots.jl#2337 should still be open
from plotdocs.jl.
Point 1. has finally been fixed yesterday (#318 - #320). When searching for e.g. show_empty_bins
, a search results pointing to https://docs.juliaplots.org/stable/generated/attributes_series/ is proposed.
You can search for attributes but also aliases now.
Not sure about 2. (I am not sure that the proposed approach would enhance clarity).
Point 3. is a julia
language pre-requisite and has nothing to do with Plots
, although since beginners are likely to use Plots
rapidly, we could maybe add a link to https://docs.julialang.org/en/v1/manual/types/#Type-Unions and a note in the attributes page. Maybe somewhere around here: https://github.com/JuliaPlots/PlotDocs.jl/blob/master/src/PlotDocs.jl#L267-L270.
from plotdocs.jl.
Point 1. has finally been fixed yesterday (#318 - #320). When searching for e.g.
show_empty_bins
, a search results pointing to https://docs.juliaplots.org/stable/generated/attributes_series/ is proposed. You can search for attributes but also aliases now.
If I search show_empty_bins
, the relevant hits with the list of attributes are the last two. I'm not sure about the details of the search mechanism with Documenter.jl
. This may be an issue with that package.
If I search markersize
, the first result should point straight to the page that has the information about this attribute. But this page is far down the list, and it's not obvious which one. (It's the one called "Series Attributes") Also, if I search for its alias ms
, it's basically at the bottom of the results.
Maybe the attribute pages need to be prioritized more in the search results.
Not sure about 2. (I am not sure that the proposed approach would enhance clarity).
I think it would enhance clarity greatly. I'm not the only one that has been frustrated with finding attribute documentation. See here, here, here. Also, anecdotes from my friends. I'm motivated to fix this partly because this was by far the most frustrating thing about learning Julia for me.
I remember trying to figure out how to manipulate the legend and could not figure out which one of Series, Plot, Subplot, and Axis had the entries for legend attributes, even after many iterations. But if they were all listed under a section called "Legend Attributes," it would be obvious. Legend attributes was particularly confusing since one can have a plot of lines and points all on the same canvas, with one legend, and yet the attributes are listed under Subplot, not Plot.
Point 3. is a
julia
language pre-requisite and has nothing to do withPlots
, although since beginners are likely to usePlots
rapidly, we could maybe add a link to https://docs.julialang.org/en/v1/manual/types/#Type-Unions and a note in the attributes page. Maybe somewhere around here: https://github.com/JuliaPlots/PlotDocs.jl/blob/master/src/PlotDocs.jl#L267-L270.
The type system is indeed something baked into the language itself. However, it is a good idea to explain the types and give examples of the possible values that it can take. This is especially important since beginners and many end-users do not regularly use or encounter abstract types, yet these are the very people that probably want to understand what the attributes mean.
To give another example, bins
has the type
Union{Integer, Symbol, Tuple{Integer, Integer}, AbstractVector}
but a lot of people don't know that StepRange <: AbstractVector
, or may be confused by Int
vs. Integer
.
Instead, here is how I would write the following doc entry:
bins :: Union{Integer, Symbol, Tuple{Integer, Integer}, AbstractVector}
Defines the number of bins. Aliases :bin
, :nb
, :nbin
, :nbins
.
Can take in one of the following types:
Integer
– defines the approximate number of bins to aim for. Not guaranteed to give the exact value.bins=10
gives a 1D histogram with about 10 bins.bins=10
gives a 2D histogram with about 10 bins for each dimension.
Tuple{Integer, Integer}
– for two-dimensional histograms, defines the approximate number of bins per dimension. Not guaranteed to give the exact values.bins=(10, 20)
gives a 2D histogram with about 10 bins for thex
dimension and about 20 bins for they
dimension.
Symbol
– defines the auto-binning algorithm to use.:sturges
– Sturges' rule:sqrt
– Square root rule:rice
– Rice rule:scott
– Scott's normal reference rule:fd
(default) – Freedman-Diaconis' rule
AbstractVector
– defines a vector of values for bin edges.bins=range(-10, 10, length=21)
gives a histogram with bins starting from -10, ending at 10, and containing 21 break values, giving 20 bins.
Relevant attribute for the following series types:
This is the type of entry I'd like to see for every single attribute that exists.
from plotdocs.jl.
If I search show_empty_bins, the relevant hits with the list of attributes are the last two. I'm not sure about the details of the search mechanism with Documenter.jl. This may be an issue with that package.
Yeah well I didn't say it was perfect. The current solution is monkey patching the domify
method from Documenter
in order to tweak the search index when using raw html tables:
Lines 14 to 48 in 4809512
I agree that it would be better to weight the search result in order to make the result appear at the top of the results. As you can see in search.js, there is a boost field, that we could use to tweak the search order. I gave it a try but couldn't find a solution while implementing #318 (which in the end is just a hack).
But if they were all listed under a section called "Legend Attributes," it would be obvious.
That could work, but that would need some effort to integrate smoothly in Plots
and PlotDocs
. It's "only" a matter of putting in development time, and producing something not being too convoluted and difficult to maintain because of its complexity.
Instead, here is how I would write the following doc entry:
That looks nice indeed. Currently you can see that the description types are defined here. If you can make it work without increasing the complexity too much I'd be happy to integrate this, but be aware that implementing a clean and generic solution for the arguments and their description might be non-trivial.
from plotdocs.jl.
With the entry I wrote, I think it's a bit too complex to be included as part of a dictionary. The majority of attributes won't be as complex as bins
, but there are still quite a few that need more than a few lines to completely document.
My idea is the tables should be replaced with pages that resemble the API page. The disadvantages with the tables right now is that the attributes cannot directly be searched, and the amount of information for a given attribute is softly constrained by a box. (Not an actual constraint...but the dictionary+table format strongly suggests terse descriptions) Additionally, there seems to be a lot of inherent complications that are coming from the fact that it's the Plots.jl repository generating the attribute tables.
With the API pages, all the information I wrote can be put into an entry for bins
and formatted just like above, and it will also be easier to search for the particular attribute in the search bar (but enhancing the search itself should be a separate issue).
One issue is how to include this information in the REPL. Right now, typing plotattr("bins")
gives the information, but it is different than typing ?bins
since bins
has to be a method, and ?plotattr("bins")
won't work. Is there a way to make this work if the attributes were documented on an API page? I understand that this is not how keywords are normally documented...
I'm willing to put in the work to recategorize all of the attributes and create separate API pages for each of them. Just want to figure out the best way to approach this.
from plotdocs.jl.
One way to recategorize them is the following:
- Series attributes stay the same. On the API page, every entry contains a "Relevant attribute for the following series types:" list that denotes all of the series types which the attribute can modify.
- Plot attributes is renamed to Global attributes. This is probably a less ambiguous word to refer to those attributes which impact the entire plot.
- Subplot attributes are split up into the following categories:
- Annotation attributes:
annotationcolor
annotationfontfamily
annotationfontsize
annotationhalign
annotationrotation
annotations
annotationvalign
- Colorbar attributes:
clims
colorbar
colorbar_continuous_values
colorbar_discrete_values
colorbar_fontfamily
colorbar_formatter
colorbar_scale
colorbar_tickfontcolor
colorbar_tickfontfamily
colorbar_tickfonthalign
colorbar_tickfontrotation
colorbar_tickfontsize
colorbar_tickfontvalign
colorbar_ticks
colorbar_title
colorbar_title_location
colorbar_titlefontcolor
colorbar_titlefontfamily
colorbar_titlefonthalign
colorbar_titlefontrotation
colorbar_titlefontsize
colorbar_titlefontvalign
- Legend attributes:
legend_background_color
legend_column
legend_font
legend_font_color
legend_font_family
legend_font_halign
legend_font_pointsize
legend_font_rotation
legend_font_valign
legend_foreground_color
legend_position
legend_title
legend_title_font
legend_title_font_family
legend_title_font_halign
legend_title_font_pointsize
legend_title_font_rotation
legend_title_font_valign
- Margin attributes:
bottom_margin
left_margin
margin
right_margin
top_margin
- Title attributes:
title
titlefontcolor
titlefontfamily
titlefonthalign
titlefontrotation
titlefontsize
titlefontvalign
titlelocation
- 3D-specific attributes:
camera
projection
projection_type
- Other subplot attributes:
aspect_ratio
background_color_inside
background_color_subplot
color_palette
extra_kwargs
fontfamily_subplot
foreground_color_subplot
foreground_color_title
framestyle
subplot_index
- Annotation attributes:
- Axis attributes stay the same.
We might also want to consider making the attribute names consistent with regards to spacing, snake-case, etc. Right now, all the annotation attributes are concatenated words, the colorbar attributes are all over the place, the legend attributes are all snakecase, and the title attributes are concatenated. Also, clims
(colorbar limits) has an official name that is different from the other colorbar attributes.
from plotdocs.jl.
What we shouldn't change is that there is a single source of truth.
On the other hand I don't see a reason why you couldn't generate the markdown in #323 (comment) from the current stucture when you change the descripion string in Plots.jl.
I would probably like to have a frontpage that only lists the attributes as links, such that you get the detailed information if you click on it.
from plotdocs.jl.
On the other hand I don't see a reason why you couldn't generate the markdown in #323 (comment) from the current stucture when you change the descripion string in Plots.jl.
I'm not sure I follow. It is technically possible to fit all of the information in the table, but it wouldn't look good as the last column would take up too much space. There's a bunch of nested bullet points, and for some attributes, the list of relevant series types which the attribute applies to can be huge. The information really needs the entire space on the page to be readable, not just a single column. A tabular format encourages terse docstrings, so it would be nice to have more information to enhance accessibility. Plus, right now the backticks don't render in the table, and there is the occasional \n
in the descriptions.
Essentially, my position is this: I know what format I want to present the information to be as complete and concise as possible, and am thinking the present table is not adequate enough to realize that, but function docstrings do. Thus the question becomes how to replicate the function docstring format as closely as possible within the limits of Documenter.jl. If the attribute names themselves show up on the results page when searching in the docs, that would help greatly with discoverability.
from plotdocs.jl.
I'm not saying we should keep that table. We can generate from the dictionary in Plots.jl/src/attr_descr.jl
any markdown.
from plotdocs.jl.
Does the information have to be written as part of a dictionary, or can I write the markdown directly? Using ##
and ###
headers would be good enough for organization.
from plotdocs.jl.
In principle its fine to use markdown stings there, however we should take care not to break usage of that information in plotattr
and docstrings.
Thats either keeping the dictionary structure or also changing how these functions use that information.
from plotdocs.jl.
One way is to keep the dictionary as-is, but create new pages with pure Markdown, replacing the generated/attribute_series.md
, etc. That way plotattr
functionality won't be broken. There'll be a disconnect between documentation on the site and documentation as seen in the REPL via plotattr
, but I think this'll be a good start. What do you think?
from plotdocs.jl.
Sounds reasonable to me
from plotdocs.jl.
Example for series attributes. While creating this page, it was found that match_dimensions
was not being generated in the table.
from plotdocs.jl.
Related Issues (20)
- Add documentation on functions gif, mov, mp4 and webm.
- GR Backend: Colorbar title text inside ticks HOT 2
- join GSoD'22? HOT 3
- `PlotlyJS` gallery is failing to show the rendered image HOT 1
- Custom ticks on a log scale in PGFPlots is broken
- normed options for histogram is not documented HOT 2
- could not load library "libGR.so" HOT 1
- Legend not well documented HOT 1
- Search often not showing most relevant results HOT 2
- All attributes manuals are broken HOT 3
- Plotly plot not displaying in tutorial HOT 5
- using Plots; pyplot() breaks docs HOT 1
- Pipeline example broken HOT 7
- Table shows unevaluated Markdown HOT 1
- Using variables in sizing subplots via curly brackets HOT 1
- Document `:latex` functionality for axis attribute `formatter` HOT 1
- kindlmann colormap HOT 1
- matplotlib API change blocked CI. HOT 1
- Precompile fails in Julia 1.10.3: buffer overflow HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from plotdocs.jl.