Plots.jl: Plot attributes are not searchable in the docs

[BeastyBlacksmith]

I think this is a main painpoint of discoverability, especially for attributes that doesn't have documentation beyond an entry in the attributes list.

[mkborregaard]

not a solution but do you know

julia> plotattr()
Specify an attribute type to get a list of supported attributes. Options are Series, Subplot, Plot, Axis

julia> plotattr(:Series)
Defined Series attributes are:
arrow, bar_edges, bar_position, bar_width, bins, colorbar_entry, contour_labels, contours, fill_z, fillalpha, fillcolor, fillrange, group, hover, label, levels, line_z, linealpha, linecolor, linestyle, linewidth, marker_z, markeralpha, markercolor, markershape, markersize, markerstrokealpha, markerstrokecolor, markerstrokestyle, markerstrokewidth, match_dimensions, normalize, orientation, primary, quiver, ribbon, series_annotations, seriesalpha, seriescolor, seriestype, show_empty_bins, smooth, stride, subplot, weights, x, xerror, y, yerror, z

julia> plotattr("marker_z")
marker_z {AbstractVector, Function `f(x,y,z) -> z_value`, or Function `f(x,y) -> z_value`, or nothing}
marker_zs, markerz, mz, zcolor

z-values for each series data point, which correspond to the color to be used from a markercolor gradient.
Series attribute,  default: nothing

[BeastyBlacksmith]

I know, but especially newcomers don't

[BeastyBlacksmith]

It would also be good to have example invocations in these attribute docstrings.

[TheCedarPrince]

5/26/2020

Per conversation with Simon, this is not a trivial solution to implement. According to him, the problem with the searching of attributes comes from Documenter.jl when it auto-generates the attributes pages (i.e. Series, Plot, Subplot, Axis attributes). It appears that even though there are two discrete repositories for the Julia Plots project (Plots.jl and PlotDocs.jl), the documentation that is generated by Documenter.jl comes from both these repositories. In the case of the attributes pages, it is being directly generated from the Plots.jl repo.

I am currently investigating how Documenter.jl handles this behavior and why the automatically generated files are not searchable.

5/28/2020

Purpose of Documenter.jl: combine markdown files and inline docstrings from Julia's docsystem into a single inter-linked document.

1. Needs one Julia package for which to document. Can come from PkgDev.generate or it can be from a .jl file via Julia's LOAD_PATH.

2. Each repository for documentation has the following structure:

Example/
├── docs/
│   └── ...
├── src/
│   └── Example.jl
...

1. Finally, inside the docs folder, two fies are needed. A src/ folder to store the markdown documentation and a make.jl file that maintains the building process for the document.

In PlotDocs.jl, the files for attributes are being generated from src/make.jl and apparently are not stored anywhere on the PlotDocs.jl repo. Instead they are automatically stored in a apparent temporary folder called generated/ that is removed by Documenter.jl after document generation.

6/2/2020

Continued working on understanding the make.jl folder in the root of PlotDocs. This time, I was able to determine that the item of suspicion that causes the error with bad indexing comes from the /src/PlotDocs.jl file.

Will continue to keep exploring the method as to why attributes are not being accurately indexed.

6/11/2020

After becoming distracted a while with LiveServer.jl errors, I was able to render the documentation locally per help from Simon! All one has to do is navigate to the PlotDocs repo, clone it, and then run julia /[path-to-clone]/PlotDocs/docs/make.jl.

The make will take about 15 - 29 minutes the first time. Once done, go into the build folder and open the index.html file in your web browser. The documentation should now be built locally!

Now, onto replicating the error.

6/16/2020

Pinged the Documenter.jl team about this issue via Julia Slack. Was given a lead to check things out:

"Probably not the ideal fix, but there is a file generated build/search_index.js which contains a simple JSON list of objects with {location, page, title, text, category} (My hunch is these are generated by the Documenter.Anchors). If you created an entry that has the location page and title of all the attributes, then for the text just put the whole table in, and then for the category put "section" and it should work (maybe?)." - Miles Lucas (aka @mileslucas)

"Maybe try to use a regular markdown table instead of https://github.com/JuliaPlots/PlotDocs.jl/blob/49dc6bb16e025644f6707c811e5990e3e14e1675/src/PlotDocs.jl#L236 would help?" - Fredrik Ekre (aka @fredrikekre)

6/18/2020

Was able to successfully investigate the rationale put forth by @mortenpi. Absolutely correct in the assessment that rendering to HTML is causing the issue. Not sure how to exactly proceed in repairing this problem.

[BeastyBlacksmith]

I didn't meant that the issue is that they are generated, rather that they are in table format and not plain markdown and that this does not get searched by the search bar.

[TheCedarPrince]

Hey @BeastyBlacksmith, still working on this issue but I ran into a issue trying to reproduce this issue. I am trying to host PlotDocs locally via LiveServer and cannot get LiveServer to render the docs locally.

Two questions:

1. Do you use LiveServer to render the documentation locally? Or how do you do that?

2. How do you test Documenter.jl's output locally?

Thanks!

[BeastyBlacksmith]

I just run the make.jl file locally and then open index.html in a browser

[TheCedarPrince]

Perfect! Thanks for the help @BeastyBlacksmith!

I will be continuing on with tracking down this error.

[mortenpi]

rather that they are in table format and not plain markdown and that this does not get searched by the search bar

Yup, it's because they are in these at-raw HTML blocks. Documenter doesn't know how to interpret HTML, so we can't generate a useful index for them.

Just a few quick breadcrumbs to understand Documenter better:

1. Documenter generates the search index when we're writing out the HTML. As we run through the Markdown tree, we also push items to the search index (e.g. here), which eventually gets written out as search_index.js.
2. The index then gets read in by this lunr.js-based search script, which runs the search in the browser.

If you want to stick to the raw HTML tables (as opposed to using Markdown tables), an idea, although a bit hacky, would be to monkey-patch Documenter by providing your own domify methods that would write out index entries for the table.

[daschw]

Thanks for the info! If I remember correctly, the reason I chose raw HTML tables, was that markdown tables were too big with that much content and I could not reduce font size.

[TheCedarPrince]

I was able to switch the rendering of the table. I can definitely confirm what @mortenpi is saying is the issue. @daschw and @BeastyBlacksmith, what would you like me to do next here? I don't want to start doing something that might drastically change the documentation layout. Thoughts?

Thank you!

[BeastyBlacksmith]

Hmm... I would value the searchability over concise display, but if you are able to pull off the monkey patching so we get both, I would be in favor of that.

[TheCedarPrince]

Hey @BeastyBlacksmith,

Both are beyond my ability with Documenter.jl. I am going to go on a brief hiatus from this problem and give a deeper look at Documenter.jl. In the interim, if someone solves this issue, great. Otherwise, I will return sometime to see what I can do. Thanks for all the support.

[BeastyBlacksmith]

Thank you for your investigation