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

Consistent notebook titles (and handle options/variations?) #18

Closed
ceball opened this Issue Nov 23, 2017 · 20 comments

Comments

Projects
None yet
4 participants
@ceball
Copy link
Member

ceball commented Nov 23, 2017

Notebooks might be viewed:

  • in jupyter notebook server (or jupyter lab)
  • on github
  • when turned into standalone html
  • or when used as part of a website.
  • ...

Notebooks always have a filename, which in some views might be prominent/title like, while in others invisible. Notebooks might also have a title (a markdown header) in the first cell.

Here's an example of viewing a notebook in various ways, from holoviews:

jupyter notebook server:
screen shot 2017-11-23 at 2 15 42 pm

github:
screen shot 2017-11-23 at 2 16 08 pm

standalone html:
screen shot 2017-11-23 at 2 19 23 pm

web site:
screen shot 2017-11-23 at 2 15 34 pm

In holoviews, notebooks have filenames like 01-Amazing_Thing.ipynb or 1-Another_Amazing_Thing.ipynb (or just amazing_thing.ipynb, depending whether part of an ordered or unordered collection of notebooks). Notebooks have a first cell that's a markdown level 1 heading, like # Amazing Thing or # Another Amazingly Amazing Thing (i.e. something at least kind of similar to the filename). When building holoviews.org and turning a notebook into html as part of the site, holoviews skips the first cell and constructs the title from the filename.

In anacondaviz (for example), notebooks have filenames like 04-working-with-datasets.ipynb or Appendix-1-exploration-with-containers.ipynb. Notebooks have a first cell like this:

  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href='http://www.holoviews.org'><img src=\"assets/hv+bk.png\" alt=\"HV+BK logos\" width=\"40%;\" align=\"left\"/></a>\n",
    "<div style=\"float:right;\"><h2>04. Working with multi-dimensional datasets</h2></div>"
   ]
  },

We can do anything we want when building a site, and handle any options, but is it possible to have a convention (or couple of conventions, e.g. for ordered vs unordered) which we encourage and use by default?

@ceball ceball self-assigned this Nov 23, 2017

@ceball ceball changed the title Better handling of notebook titles Consistent notebook titles (and handle options/variations?) Nov 23, 2017

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 23, 2017

I think notebook titles can map to webpage titles with a simple scheme:

  1. Strip out any leading numbers that may be in the notebook title to order the notebooks (useful when working through a sequence of notebooks, e.g for a tutorial).
  2. Replace underscores (and dashes?) in the notebook title with spaces.

I think the ordering using leading numbers might be useful for controlling more subtle things in the docs, e.g ordering in the table of contents.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 23, 2017

Note, that this suggestion means that I think the ordering of notebooks with a numeric prefix should be allowed, supported but also optional.

@ceball

This comment has been minimized.

Copy link
Member Author

ceball commented Nov 23, 2017

To me it's confusing that holoviews has a notebook with filename 2-Customization.ipynb (and hence 'notebook title' in the notebook server of 2-Customization), but which has an internal title (in the notebook itself) of Customizing visual appearance, and a title on the website of Customization. I can't tell what the intended title is supposed to be.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 23, 2017

I agree it is confusing and inconsistent but I also think that the title in the notebook does not necessarily have to match the filename (even after removing any numeric prefix/underscores). I'll need to think about it more.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 23, 2017

@jlstevens, I suppose we're following Bokeh's style in this case, with no explicit numbering visible.
My own feeling is that retaining the numbers in tables of contents and titles helps make it clear that the content is organized and ordered in a certain way, but I guess I don't have a terribly strong opinion about that. Otherwise, I think that renaming scheme is fine, perhaps augmented by forcing an initial capital letter when making a webpage title.

@ceball, I agree that it's confusing and that we should simplify it. I can only think of two defensible, non-confusing alternatives here, with my own preference being for option 1 (implicit headings), and the current behavior mostly corresponding to option 2, but perhaps not exactly:

  1. Implicit heading (aka filename as heading): Omit the initial heading from the notebook page, and assume that the filename will be used by the notebook server or by the website, reformatted slightly as needed.
    Pros: Simple, unambiguous, concise. Only one source of page titles, always consistently.
    Cons:

    1. A pure HTML report or Github rendering will not show any large heading (though it will usually show the filename in tiny print somewhere if printed, and it will have a URL if viewed online).
    2. Can lead to complicated filenames, including awkward capitalizations.
  2. Explicit heading (aka ignore filenames): Use the filename for ordering and to refer to files, but never format show it on screen or in TOCs.
    Pros: Allows arbitrary titles. Ensures title is always visible.
    Cons:

    1. Has two redundant sources of information, sometimes both visible (e.g. in a live Jupyter notebook)
    2. Confusing when title doesn't match the filename, in those cases where the filename is visible
    3. Requires people to put content in the notebook in a certain way
    4. Gives two titles on the page in cases we can't control (e.g. in Jupyter itself)
    5. Requires either parsing the file to extract the heading for use in TOCs and links, or else will be inconsistent between the page title and the link title, neither of which are desirable.

My own feeling is that using implicit headings is simpler, easier to describe, and less confusing. It can be awkward to have complicated filenames, but (a) encouraging simple titles is not a bad thing, and (b) with tab completion, who cares? But @philippjfr may have a different opinion, since if I recall correctly he's the one who shifted towards explicit headings when making the current holoviews website?

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 24, 2017

I think option 1. would be a reasonable decision but I would prefer to keep the ordering while dropping the numeric prefix for anything shown on the website. I feel those numbers are mainly for ordering notebooks when working through an ordered collection of them in the notebook file browser.

@philippjfr

This comment has been minimized.

Copy link
Contributor

philippjfr commented Nov 24, 2017

But @philippjfr may have a different opinion, since if I recall correctly he's the one who shifted towards explicit headings when making the current holoviews website?

That was mostly driven by two things a) when I added long/descriptive notebook filenames I got comments saying they were too long/complex and b) we decided on a no capitalization rule for most of our notebooks (although we probably didn't follow this uniformly), so there is no easy way to recover the proper capitalization for a readable title. Personally I think forcing all titles to be generated from the notebook filenames is too restrictive especially for a project that is meant for general use.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 24, 2017

Thanks for the background; that's helpful. I think there are a few different concepts here that we should be careful to consider separately. Specifically, for each notebook we need:

a. a filename (preferably short, typically lower case in UNIX)
b. a short handle to use in website/notebook links between pages (preferably short, typically mixed case)
c. a short handle to use in the TOC and sidebar (preferably short, typically mixed case)
d. a title for the HTML page (preferably short, typically mixed case)
e. a heading at the top of the page (can be longer, typically mixed case)

It's possible to have different values for each of these, to optimize them individually, which we are currently doing in some cases. E.g. having e be different from a allows us to have more expressive, precise titles than would be practical as filenames. That makes sense and is reasonable, but on balance I think there are more important things for us to optimize. Specifically, I think we should prioritize the experience of a user as they work with all of these while navigating our websites. And to me it seems like it reduces the users' cognitive load if a-e are all the same thing, giving them only one label to try to process and recognize as they click around and run the examples themselves. The TOC already has full sentences describing the content, which seems sufficient to me to cover the expressivity issues.

Any of the options that don't involve a-e being the same seem problematic to me. E.g. if we argue for a to be shorter and lower case to make for a nice, short handle for referring to the notebook, then what about b-d? Nice and short handles are useful there too, but lower case isn't, so we'd end up with three different labels per notebook (a (short, lowercase), b-d (short, mixed case), and e (long, mixed case))? That seems very confusing for our users, and will make it more difficult for them to realize when they encounter a certain link or filename whether they have read it or seen that material or not. I think once they click on a link, they should end up somewhere clearly labeled with what they clicked on, reinforcing to the user that single shared concept. For this to work, we would need to have relatively short titles that make sense as handles, and then just use them everywhere.

If we look at the current holoviews user guide, there are actually very few differences, and the ones that are there seem to me to add to confusion, not reduce it:

Filename:                                TOC entry:
01-Annotating_Data.ipynb                 Annotating your Data                 
02-Composing_Elements.ipynb              Composing Elements                   
03-Customizing_Plots.ipynb               Customizing Plots                    
04-Dimensioned_Containers.ipynb          Dimensioned Containers               
05-Building_Composite_Objects.ipynb      Building Composite Objects           
06-Live_Data.ipynb                       Live Data                            
07-Tabular_Datasets.ipynb                Tabular Datasets                     
08-Gridded_Datasets.ipynb                Gridded Datasets                     
09-Indexing_and_Selecting_Data.ipynb     Indexing and Selecting Data          
10-Transforming_Elements.ipynb           Transforming Elements                
11-Responding_to_Events.ipynb            Responding to Events                 
12-Custom_Interactivity.ipynb            Custom Interactivity                 
13-Data_Pipelines.ipynb                  Data Processing Pipelines            
Network_Graphs.ipynb                     Creating interactive network graphs  
14-Large_Data.ipynb                      Working with large data              
15-Streaming_Data.ipynb                  Working with streaming data          
16-Dashboards.ipynb                      Creating interactive dashboards      
Continuous_Coordinates.ipynb             Continuous Coordinates
Deploying_Bokeh_Apps.ipynb               Deploying Bokeh Apps
Exporting_and_Archiving.ipynb            Exporting and Archiving
Installing_and_Configuring.ipynb         Installing and Configuring HoloViews  (not linked in user guide?)
Plots_and_Renderers.ipynb                Working with Plot and Renderers
Plotting_with_Bokeh.ipynb                Plotting with Bokeh
Plotting_with_Matplotlib.ipynb           Plotting with matplotlib
Tips_and_Tricks.ipynb                    Tips and Tricks (not rendered on site?)

I don't think any of these differences improve clarity as much as they add multiplicity.

Looking at the rest of the HV site, there are 142 notebooks that have capitals in the name (mostly in getting_started, reference, user_guide), and 64 that don't (mostly in gallery and topics). I think that if we were going to have lowercase filenames, we should have them everywhere consistently, so that people can easily and immediately distinguish between handles (filenames, always lowercase and short) and titles (upper case, sometimes long). I.e. we could have "01-annotating_data.ipynb", to be linked and titled "Annotating Data". Having them be nearly the same but not quite is more confusing than either having them entirely different or always exactly the same. But filenames won't actually work for most of the cases where we need a short handle, so I don't think this approach solves the underlying issues.

For reference, here are the filenames with mixed case:

0172-jbednar:~/holoviews/examples> find . | \grep ipynb'$' | \grep -v checkpoints | \grep '[A-Z]'
./getting_started/0-Installation.ipynb
./getting_started/1-Introduction.ipynb
./getting_started/2-Customization.ipynb
./getting_started/3-Tabular_Datasets.ipynb
./getting_started/4-Gridded_Datasets.ipynb
./getting_started/5-Live_Data.ipynb
./reference/containers/bokeh/DynamicMap.ipynb
./reference/containers/bokeh/GridSpace.ipynb
./reference/containers/bokeh/HoloMap.ipynb
./reference/containers/bokeh/Layout.ipynb
./reference/containers/bokeh/NdLayout.ipynb
./reference/containers/bokeh/NdOverlay.ipynb
./reference/containers/bokeh/Overlay.ipynb
./reference/containers/matplotlib/DynamicMap.ipynb
./reference/containers/matplotlib/GridSpace.ipynb
./reference/containers/matplotlib/HoloMap.ipynb
./reference/containers/matplotlib/Layout.ipynb
./reference/containers/matplotlib/NdLayout.ipynb
./reference/containers/matplotlib/NdOverlay.ipynb
./reference/containers/matplotlib/Overlay.ipynb
./reference/elements/bokeh/Area.ipynb
./reference/elements/bokeh/Arrow.ipynb
./reference/elements/bokeh/Bars.ipynb
./reference/elements/bokeh/Bivariate.ipynb
./reference/elements/bokeh/Bounds.ipynb
./reference/elements/bokeh/Box.ipynb
./reference/elements/bokeh/BoxWhisker.ipynb
./reference/elements/bokeh/Contours.ipynb
./reference/elements/bokeh/Curve.ipynb
./reference/elements/bokeh/Distribution.ipynb
./reference/elements/bokeh/Ellipse.ipynb
./reference/elements/bokeh/ErrorBars.ipynb
./reference/elements/bokeh/Graph.ipynb
./reference/elements/bokeh/HeatMap.ipynb
./reference/elements/bokeh/Histogram.ipynb
./reference/elements/bokeh/HLine.ipynb
./reference/elements/bokeh/HSV.ipynb
./reference/elements/bokeh/Image.ipynb
./reference/elements/bokeh/ItemTable.ipynb
./reference/elements/bokeh/Path.ipynb
./reference/elements/bokeh/Points.ipynb
./reference/elements/bokeh/Polygons.ipynb
./reference/elements/bokeh/QuadMesh.ipynb
./reference/elements/bokeh/Raster.ipynb
./reference/elements/bokeh/RGB-Copy1.ipynb
./reference/elements/bokeh/RGB.ipynb
./reference/elements/bokeh/Scatter.ipynb
./reference/elements/bokeh/Spikes.ipynb
./reference/elements/bokeh/Spline.ipynb
./reference/elements/bokeh/Spread.ipynb
./reference/elements/bokeh/Table.ipynb
./reference/elements/bokeh/Text.ipynb
./reference/elements/bokeh/VectorField.ipynb
./reference/elements/bokeh/VLine.ipynb
./reference/elements/matplotlib/Area.ipynb
./reference/elements/matplotlib/Arrow.ipynb
./reference/elements/matplotlib/Bars.ipynb
./reference/elements/matplotlib/Bivariate.ipynb
./reference/elements/matplotlib/Bounds.ipynb
./reference/elements/matplotlib/Box.ipynb
./reference/elements/matplotlib/BoxWhisker.ipynb
./reference/elements/matplotlib/Contours.ipynb
./reference/elements/matplotlib/Curve.ipynb
./reference/elements/matplotlib/Distribution.ipynb
./reference/elements/matplotlib/Ellipse.ipynb
./reference/elements/matplotlib/ErrorBars.ipynb
./reference/elements/matplotlib/Graph.ipynb
./reference/elements/matplotlib/HeatMap.ipynb
./reference/elements/matplotlib/Histogram.ipynb
./reference/elements/matplotlib/HLine.ipynb
./reference/elements/matplotlib/HSV.ipynb
./reference/elements/matplotlib/Image.ipynb
./reference/elements/matplotlib/ItemTable.ipynb
./reference/elements/matplotlib/Path.ipynb
./reference/elements/matplotlib/Points.ipynb
./reference/elements/matplotlib/Polygons.ipynb
./reference/elements/matplotlib/QuadMesh.ipynb
./reference/elements/matplotlib/Raster.ipynb
./reference/elements/matplotlib/RGB.ipynb
./reference/elements/matplotlib/Scatter.ipynb
./reference/elements/matplotlib/Scatter3D.ipynb
./reference/elements/matplotlib/Spikes.ipynb
./reference/elements/matplotlib/Spline.ipynb
./reference/elements/matplotlib/Spread.ipynb
./reference/elements/matplotlib/Surface.ipynb
./reference/elements/matplotlib/Table.ipynb
./reference/elements/matplotlib/Text.ipynb
./reference/elements/matplotlib/Trisurface.ipynb
./reference/elements/matplotlib/VectorField.ipynb
./reference/elements/matplotlib/VLine.ipynb
./reference/elements/plotly/BoxWhiskers.ipynb
./reference/elements/plotly/Curve.ipynb
./reference/elements/plotly/Distribution.ipynb
./reference/elements/plotly/ErrorBars.ipynb
./reference/elements/plotly/HeatMap.ipynb
./reference/elements/plotly/Image.ipynb
./reference/elements/plotly/ItemTable.ipynb
./reference/elements/plotly/Points.ipynb
./reference/elements/plotly/Raster.ipynb
./reference/elements/plotly/Scatter.ipynb
./reference/elements/plotly/Scatter3D.ipynb
./reference/elements/plotly/Surface.ipynb
./reference/elements/plotly/Table.ipynb
./reference/elements/plotly/Trisurface.ipynb
./reference/streams/bokeh/Bounds.ipynb
./reference/streams/bokeh/BoundsX.ipynb
./reference/streams/bokeh/BoundsY.ipynb
./reference/streams/bokeh/PointerX.ipynb
./reference/streams/bokeh/PointerXY.ipynb
./reference/streams/bokeh/RangeXY.ipynb
./reference/streams/bokeh/Selection1D.ipynb
./reference/streams/bokeh/Selection1D_paired.ipynb
./reference/streams/bokeh/Selection1D_points.ipynb
./reference/streams/bokeh/Selection1D_tap.ipynb
./reference/streams/bokeh/Tap.ipynb
./user_guide/01-Annotating_Data.ipynb
./user_guide/02-Composing_Elements.ipynb
./user_guide/03-Customizing_Plots.ipynb
./user_guide/04-Dimensioned_Containers.ipynb
./user_guide/05-Building_Composite_Objects.ipynb
./user_guide/06-Live_Data.ipynb
./user_guide/07-Tabular_Datasets.ipynb
./user_guide/08-Gridded_Datasets.ipynb
./user_guide/09-Indexing_and_Selecting_Data.ipynb
./user_guide/10-Transforming_Elements.ipynb
./user_guide/11-Responding_to_Events.ipynb
./user_guide/12-Custom_Interactivity.ipynb
./user_guide/13-Data_Pipelines.ipynb
./user_guide/14-Large_Data-Copy1.ipynb
./user_guide/14-Large_Data.ipynb
./user_guide/15-Streaming_Data.ipynb
./user_guide/16-Dashboards.ipynb
./user_guide/Continuous_Coordinates.ipynb
./user_guide/Deploying_Bokeh_Apps.ipynb
./user_guide/Exporting_and_Archiving.ipynb
./user_guide/Installing_and_Configuring.ipynb
./user_guide/Network_Graphs.ipynb
./user_guide/Plots_and_Renderers.ipynb
./user_guide/Plotting_with_Bokeh.ipynb
./user_guide/Plotting_with_Matplotlib.ipynb
./user_guide/Tips_and_Tricks.ipynb

And here are the ones in lower case:

0172-jbednar:~/holoviews/examples> find . | \grep ipynb'$' | \grep -v checkpoints | \grep -v '[A-Z]'
./gallery/demos/bokeh/area_chart.ipynb
./gallery/demos/bokeh/autompg_histogram.ipynb
./gallery/demos/bokeh/bachelors_degrees_by_gender.ipynb
./gallery/demos/bokeh/bars_economic.ipynb
./gallery/demos/bokeh/boxplot_chart.ipynb
./gallery/demos/bokeh/dot_example.ipynb
./gallery/demos/bokeh/dragon_curve.ipynb
./gallery/demos/bokeh/dropdown_economic.ipynb
./gallery/demos/bokeh/histogram_example.ipynb
./gallery/demos/bokeh/iris_density_grid.ipynb
./gallery/demos/bokeh/iris_example.ipynb
./gallery/demos/bokeh/iris_splom_example.ipynb
./gallery/demos/bokeh/legend_example.ipynb
./gallery/demos/bokeh/lesmis_example.ipynb
./gallery/demos/bokeh/lorenz_attractor_example.ipynb
./gallery/demos/bokeh/mandelbrot_section.ipynb
./gallery/demos/bokeh/measles_example.ipynb
./gallery/demos/bokeh/network_graph.ipynb
./gallery/demos/bokeh/quiver_demo.ipynb
./gallery/demos/bokeh/scatter_economic.ipynb
./gallery/demos/bokeh/square_limit.ipynb
./gallery/demos/bokeh/step_chart.ipynb
./gallery/demos/bokeh/stocks_example.ipynb
./gallery/demos/bokeh/texas_choropleth_example.ipynb
./gallery/demos/bokeh/topographic_hillshading.ipynb
./gallery/demos/bokeh/us_unemployment.ipynb
./gallery/demos/bokeh/verhulst_mandelbrot.ipynb
./gallery/demos/matplotlib/area_chart.ipynb
./gallery/demos/matplotlib/autompg_histogram.ipynb
./gallery/demos/matplotlib/bachelors_degrees_by_gender.ipynb
./gallery/demos/matplotlib/bars_economic.ipynb
./gallery/demos/matplotlib/boxplot_chart.ipynb
./gallery/demos/matplotlib/dragon_curve.ipynb
./gallery/demos/matplotlib/dropdown_economic.ipynb
./gallery/demos/matplotlib/histogram_example.ipynb
./gallery/demos/matplotlib/iris_density_grid.ipynb
./gallery/demos/matplotlib/iris_example.ipynb
./gallery/demos/matplotlib/iris_splom_example.ipynb
./gallery/demos/matplotlib/legend_example.ipynb
./gallery/demos/matplotlib/lorenz_attractor_example.ipynb
./gallery/demos/matplotlib/mandelbrot_section.ipynb
./gallery/demos/matplotlib/measles_example.ipynb
./gallery/demos/matplotlib/network_graph.ipynb
./gallery/demos/matplotlib/polar_scatter_demo.ipynb
./gallery/demos/matplotlib/quiver_demo.ipynb
./gallery/demos/matplotlib/scatter_economic.ipynb
./gallery/demos/matplotlib/square_limit.ipynb
./gallery/demos/matplotlib/step_chart.ipynb
./gallery/demos/matplotlib/stocks_example.ipynb
./gallery/demos/matplotlib/surface_3d.ipynb
./gallery/demos/matplotlib/texas_choropleth_example.ipynb
./gallery/demos/matplotlib/topographic_hillshading.ipynb
./gallery/demos/matplotlib/trisurf3d_demo.ipynb
./gallery/demos/matplotlib/us_unemployment.ipynb
./gallery/demos/matplotlib/verhulst_mandelbrot.ipynb
./gallery/demos/plotly/surface_3d.ipynb
./gallery/demos/plotly/trisurf3d_demo.ipynb
./getting_started/nyc_taxi-paramnb.ipynb
./reference/features/bokeh/table_hooks_example.ipynb
./topics/geometry/lsystems.ipynb
./topics/geometry/square_limit.ipynb
./topics/simulation/boids.ipynb
./topics/simulation/hipster_dynamics.ipynb
./topics/simulation/sri_model.ipynb
@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 24, 2017

I think that if we were going to have lowercase filenames, we should have them everywhere consistently, so that people can easily and immediately distinguish between handles (filenames, always lowercase and short) and titles (upper case, sometimes long).

That is another point: we wanted our reference gallery to use capitalized notebook names as they are directly documenting classes (e.g our element classes). Philipp's comment reminded me of some of the issues that drove our decision and I think I agree with him - a simple scheme might be more consistent but also more annoying in various ways.

@ceball ceball added this to the Initial release milestone Nov 25, 2017

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 27, 2017

a simple scheme might be more consistent but also more annoying in various ways.

@jlstevens and @philippjfr, can you please elaborate? This isn't enough to go on. To me, the benefits of the simple scheme are self-evident, both for the website maintainers and the users, as outlined above. And the costs are real but seem very small in comparison. If there are costs I'm not thinking of, can you please make those clear here? A vague "more annoying in various ways" isn't enough to offset the various automated steps that can be simplified in the proposed approach.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 27, 2017

we wanted our reference gallery to use capitalized notebook names as they are directly documenting classes (e.g our element classes).

I agree with that, and it's another reason why using capitalized names in all cases just makes things easier.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 28, 2017

I agree with that, and it's another reason why using capitalized names in all cases just makes things easier.

Looking at the list of files above, capitalization is used when the filename matches the title of the notebook, either in a guide or documenting an element class. The ones in lowercase are when you need a filename that isn't a title because it is hard to give titles to demos e.g dropdown_economic.ipynb isn't a good title.

What would 'Dropdown Economic' mean? 'Economic Dropdown' wouldn't be a great title either which shows that it is hard to title a notebook like this 'Selecting Economic Data with a Dropdown Selection Menu' would be accurate and awkward both as a title and a filename.

@philippjfr

This comment has been minimized.

Copy link
Contributor

philippjfr commented Nov 28, 2017

Here's the scheme I think would work best:

There should only be one possible source for titles, which is the header line of the rst file which points to each notebook. In most cases these rst files and therefore the headers can be auto-generated from the notebooks (with conventions to strip out leading digits to allow ordering). If you want to override the default title, generated from the filename, you can commit the rst file with a custom title, which means auto-generation is skipped. This would also mean that we should delete all titles from the notebooks themselves. While this scheme wouldn't have nice titles on GitHub and in a standalone HTML file, those are not the main ways we'd expect users to explore these notebooks, so I think that it's a good compromise and would be consistent, while still allowing the flexibility of providing a custom title for the website.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 28, 2017

I'm happy with Philipp's suggestion; it's a clear, clean, and obvious mechanism.

At the same time, I think we should have a rule of thumb that we should strive not to make use of the ability to override the title except in rare cases, so that users can consistently have only one handle to deal with and can recognize the content of the page as being what a link refers to.

This way we should be able to handle any extreme cases while leaving everything as simple for users as possible.

it is hard to give titles to demos e.g dropdown_economic.ipynb isn't a good title.

I agree it's hard to give titles to demos, but it's also necessary. We have to have some way of referring to this content, and whatever it is should normally be the filename, the link text, and the title. Anything else is too confusing, in my opinion. So if "Dropdown Economic" is the best name we have for this content, then it's "Dropdown Economic", Dropdown_Economic.ipynb, and so on. We should strive to have good titles, but having some title is necessary, and having multiple titles/handles is worse than one lame but consistent title.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 28, 2017

I like Philipp's suggestion regarding autogeneration of rst titles.

I agree it's hard to give titles to demos, but it's also necessary. We have to have some way of referring to this content, and whatever it is should normally be the filename

For these demos, I do think of them in terms of their filenames precisely because we can't think of a good title that sticks. I can live with a short filename that identifies the content even if it doesn't describe it nicely enough to be a title but I'm not sure I would be happy seeing titles like "Dropdown Economic" (what does that mean?)

Maybe the solution is to follow your convention for all the things that have sensible titles but not have any title at all for demo notebooks? I am happy for those to just be a filename/URL without a title.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 28, 2017

We still need link text for them in various contexts, though.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 28, 2017

If we agree demos shouldn't have titles as they are often silly/meaningless and that we can refer to demos by the identifier that is their filename, the auto-rst generation could simply not generate titles for notebooks in lowercase, matching what we already have. Then there isn't any ambiguity as to the source of the title (I agree with Jim that you shouldn't override the autogenerated title unless necessary).

We still need link text for them in various contexts, though.

Personally, I'm happy to talk about the economic_dropdown demo, keeping the link text as the filename.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 28, 2017

In principle, using the filenames in that way seems ok, but going through the various apps and demos in http://holoviews.org/gallery , on balance I think the problem is in the demos themselves, not the titles. I.e., the demos either already have names that are usable as titles, or they don't really make sense as demos, because it's not clear what they are demoing. Here's a first pass at how I would propose to reorganize those so that they are more clearly demonstrating something, at which point they do have meaningful titles:

Area Chart                     area_chart                      
AutoMPG                        boxplot_chart + autompg_histogram
Bachelors Degrees              bachelors_degrees_by_gender     
Crossfilter                    crossfilter                     
Dot Example                    dot_example                     
Dragon Curve                   dragon_curve                    
Game of Life                   game_of_life                    
Gapminder                      gapminder                       
Histograms                     histogram_example               
Iris Species                   iris_density_grid + iris_example + iris_splom_example              
Legends                        legend_example                  
Les Miserables                 lesmis_example                  
Lorenz Attractor               lorenz_attractor_example        
Macroeconomic Data             bars_economic + dropdown_economic + scatter_economic
Mandelbrot                     mandelbrot                      
Mandelbrot Slicing             mandelbrot_section              
Measles Incidence              measles_example                 
Network Graphs                 network_graph                   
NYC Taxi with Hover            nytaxi_hover                    
Quiver                         quiver_demo                     
Square Limit                   square_limit                    
Step Chart                     step_chart                      
Stocks                         stocks_example                  
Streaming psutil               streaming_psutil                
Texas Choropleth               texas_choropleth_example        
Topographic Hillshading        topographic_hillshading         
US Unemployment                us_unemployment                 
Verhulst Mandelbrot            verhulst_mandelbrot             

Some of this depends on being able to pull out multiple plots from the same notebook for use as gallery thumbnails (discussed in pyviz/holoviews#1661), which is crucial for the Elements galleries and also would help here. These demos also each need at least a sentence saying what the point is; many of them are currently quite mysterious. But once we have such a sentence there will be a main point and thus a meaningful title for all of them.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 28, 2017

By default, I'd be happy if all plots from a notebook showed up in the gallery, unless explicitly suppressed. Better too many than to hide our wonderful stuff!

@ceball ceball referenced this issue Dec 11, 2017

Open

Website improvements TODO #28

0 of 8 tasks complete
@ceball

This comment has been minimized.

Copy link
Member Author

ceball commented Mar 9, 2018

Note: see pyviz/pyviz#44 (comment) for some instructions about the html page title.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment