-
Notifications
You must be signed in to change notification settings - Fork 96
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reorganize attribute documentation #323
Comments
These are good suggestions IMHO. See also JuliaPlots/Plots.jl#676 bit unsure whether this JuliaPlots/Plots.jl#2337 should still be open |
Point 1. has finally been fixed yesterday (#318 - #320). When searching for e.g. Not sure about 2. (I am not sure that the proposed approach would enhance clarity). Point 3. is a |
If I search If I search Maybe the attribute pages need to be prioritized more in the search results.
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.
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,
but a lot of people don't know that 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 Can take in one of the following types:
Relevant attribute for the following series types: This is the type of entry I'd like to see for every single attribute that exists. |
Yeah well I didn't say it was perfect. The current solution is monkey patching the 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).
That could work, but that would need some effort to integrate smoothly in
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. |
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 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 One issue is how to include this information in the REPL. Right now, typing 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. |
One way to recategorize them is the following:
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, |
What we shouldn't change is that there is a single source of truth. |
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 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. |
I'm not saying we should keep that table. We can generate from the dictionary in |
Does the information have to be written as part of a dictionary, or can I write the markdown directly? Using |
In principle its fine to use markdown stings there, however we should take care not to break usage of that information in |
One way is to keep the dictionary as-is, but create new pages with pure Markdown, replacing the |
Sounds reasonable to me |
Example for series attributes. While creating this page, it was found that |
The current documentation for attributes could use some refreshing.
plotattr(:Subplot)
in the REPL outputs a large list of attributes. This hinders discoverability and accessibility. In my experience, I have always had to look through all four tabs in the docs to look for an attribute.plotattr(:Subplot)
is to reorganize the categories into things like Annotation, Background, Foreground, Colorbar, Legend, Title, as well as a few others. A lot of the attribute names in this list heavily suggest this anyway. This way, when one needs to find attributes related to the legend, there is a clearly labeled tab in the docs for that, or typing e.g.plotattr(:Legend)
would yield all of its relevant attributes (cf. this issue)colorbar_ticks
could use some explaining on the different possible argument types, asUnion{Symbol, Tuple{AbstractVector{Real}, AbstractVector{AbstractString}}, AbstractVector{Real}}
is not obvious how to interpret. Also, a lot of attributes have no description.A documentation style like that on the API page would be able to solve these problems simply by allowing more room for the description, explanation of types, and examples. Categorizing them into titles like Colorbar, Legend, etc. would keep these pages manageable in length.
The text was updated successfully, but these errors were encountered: