Home page update, take 2

[jni]

A more minimal update to the home page. Rather than my previous attempt which basically required a full infrastructure update 😅, I decided to start from a more minimal template. The goal is to keep things minimal, get it merged, and then iterate.

Current layout is:

• title
• python snippet
• fancy image
• subtitle
• short paragraph
• grid of items:
  • gallery
  • installation
  • getting started
  • community
  • governance
  • plugins

That's it!

Some points I want to make:

• I think the cards need some color or something, which sphinx-design can do, but I want to leave that for a later PR.
• It's unclear whether we want a 2x3 grid or 2x2 (removing governance and plugins). I can always revert the last PR. Personally I like highlighting our governance, but I'd like a less formal document to point to. My preference is we keep this grid, and then update the governance link in a followup PR.
• The Python snippet is kinda more in your face than I actually would want it 😂. I think we should update the theme to have code be a bit smaller. But I still like the idea.
• I'd like to update the getting started page, again, follow-up PR.

Edit: another point:

• I want to change the image for a webm, and eventually a carousel of webms. Follow-up PR 😂 unless someone has something really good ready. What I think we should require:
  • greater than 2D, preferably 4D image
  • show changing viewer from 2D to 3D
  • show sliders
  • show layers
  • be simple to get to in Python code, so the code snippet can correspond to the video

Anyway, without further ado, here's what this looks like on my machine:

Bedtime for me! See you all at the docs working group meeting in ~8h! 😅

[Czaki]

Why leave here the code sample without any comment?

[psobolewskiPhD]

I agree, comments in the code could be nice, but also at least 1 line of lead in between napari and the code block would be good for me.
Also, this code doesn't make that image 🤣

[jni]

@Czaki I was inspired by matplotlib.org which shows a (much tinier) code snippet together with a plot type.

However I acknowledge that the effect here is awkward because of the size of the code snippet! 😅 When I showed the matplotlib inspiration in the docs meeting @psobolewskiPhD said, "Ok but that is way cooler!" 😂 and he's not wrong 😂

Perhaps I reduce it to:

Just

import napari
viewer, layer = napari.imshow(cells, channel_axis=1)

to get:
[video]

Alternatively, I can try to fit a caption under the image (need to check how to do that in myst):

[video/image]
viewer, layer = napari.imshow(cells, channel_axis=1)

But, I like "import napari" as a thing that people see early. 😊

Thoughts?

[Czaki]

the equivalent of matplotlib will be:

napari.imshow(cells, channel_axis=1)

As we can see also matplotlib omits an important part of the code.
Also, on video, it will be nice to show something more than just an image, but also other types of data.

[psobolewskiPhD]

I love the idea of redesigning, I love the tiles.
I don't love the abrupt nature of napari to code block.
In the docs meeting the idea was raised of having tabs showing an animated gif (or equivalent, if I understood correctly) of a (i)python centric approach, a console approach, and pure GUI approach to achieving the same thing. This resonated for me, so putting it down here too.

Also, I think installation is kinda a big deal (i know, packaging...), so I'd raise it out of Usage in the top bar and have it be the first tile.

[jni]

Also, I think installation is kinda a big deal (i know, packaging...), so I'd raise it out of Usage in the top bar and have it be the first tile.

I kinda disagree on this — installation is a thing you do once then ~very rarely (and rarely need instructions again), while everything else you check all the time. So, it should be easily accessible, but it doesn't need to take up top-bar navigation space in every page...

At any rate I don't want to update the navbar in this PR, only the home page, so maybe we continue this discussion in a later issue.

I don't love the abrupt nature of napari to code block.

Yup, will fix, see inline discussion.

In the docs meeting the idea was raised of having tabs showing an animated gif (or equivalent, if I understood correctly) of a (i)python centric approach, a console approach, and pure GUI approach to achieving the same thing. This resonated for me, so putting it down here too.

Maybe raise an issue for this? I think this requires a lot of infrastructure development that should follow this PR.

[brisvag]

I agree that the snippet + image is not the best as is. If the goal is "people should be able to copy pase this and try it", then I don't see the point of having it before the installation (since the target audience would anyways be people who didn't know napari yet).

So I lean more toward either having no snippet at all, or a simple line like @Czaki suggested.

However, the reason why the matplotlib one is cool is because it shows a specific function that's generally useful, and otherwise hard to replicate without a plotting library like matplotlib. I don't think "imview" has the same impact for me :P Would be nice to rather have a 2-3 liner (still without imports and embellishments) that also does some annotation, for example.

[Czaki]

I agree that the snippet + image is not the best as is. If the goal is "people should be able to copy pase this and try it", then I don't see the point of having it before the installation (since the target audience would anyways be people who didn't know napari yet).

It is possible (by js) to overwrite copy content. So you could have part of the code visible and the whole code will be copied on copy action.

[jni]

Ok before this conversation goes completely off the rails, I want to reiterate:

I want to change the image for a webm, and eventually a carousel of webms. Follow-up PR 😂 unless someone has something really good ready.

My plan here is to:

• change the image to a video of the cells moving the sliders around in 2D view, then switching to 3D view.
• move the code snippet to a caption under the figure.

Ultimately, time has shown that we can spend approximately infinite amount debating what exactly goes in the home page, and in the meantime the homepage remains the readme from like 3 years ago. So I suggest we merge a slightly tweaked version of the above, then iterate. Especially while #86 remains open, so the home page is not actually going to get updated, only the dev version is.

btw @brisvag

I don't think "imview" has the same impact for me

clearly you forget the world before napari. ;) Looking at a 3D+ image in Python used to be friggin annoying. And I suspect still is for a substantial portion of the scipy population.

[jni]

I don't see the point of having it before the installation

You need to get people to understand why they want to install something before they will read the installation instructions. My main thesis is that too many Python-y people find the home page and think this is a heavyweight application, not a viewer they can use from Python in their existing workflows.

[Czaki]

clearly you forget the world before napari. ;) Looking at a 3D+ image in Python used to be friggin annoying. And I suspect still is for a substantial portion of the scipy population.

but if you add labels and points with dynamic disabling and enabling on video will be much more impressing.

[jni]

but if you add labels and points with dynamic disabling and enabling on video will be much more impressing.

There is a balance between impressiveness and complexity. If the video is too complicated people might think that the tool is too complex for their simple use case. I think the carousel is the solution for this (start simple, increasing complexity).

[psobolewskiPhD]

I wonder what the traffic is like between GitHub and napari.org
Are code-y people more likely to hit the GitHub page (first)? Regardless it can for sure be more code centric than napari.org.

[brisvag]

Ok, color me convinced :) Then I vote for a 1-liner:

napari.imshow(cells, channel_axis=1)

[psobolewskiPhD]

Maybe with ndisplay=3 given that the image is in 3D mode?

[brisvag]

Not if the video starts in 2D slicing mode :)

[jni]

Here's the new look:

I'll work on video tomorrow.

[psobolewskiPhD]

I still kinda hate it 😬
I'd prefer the newly shortened text to be above the figure?
At least the A multidimensional ...
My distaste is partially driven by the empty space of the side panel/TOC area on the homepage.
The homepage doesn't use that area, it's more attractive in the more narrow layout with search at the top. Then one could try and make it more like the matplotlib homepage?
Or better yet, have the cool cards be on the left vertically (in the blank TOC area)

[brisvag]

I'd prefer the newly shortened text to be above the figure?

Yup, agree on this!

As for the rest, I also agree it's generally a bit empty, but as pointed out by @jni, we will never merge anything if we keep stopping because something else could be improved :P Let's focus on getting a good scientific image at the top, then we can discuss the rest in a followup.

[Czaki]

I prefer to remove the left empty column from the front page. Partially it is out of this PR scope but will impact the shape of the main page.

[psobolewskiPhD]

I'd prefer the newly shortened text to be above the figure?

Yup, agree on this!

As for the rest, I also agree it's generally a bit empty, but as pointed out by @jni, we will never merge anything if we keep stopping because something else could be improved :P Let's focus on getting a good scientific image at the top, then we can discuss the rest in a followup.

I mean I get that, but I think if we're redesigning—which is what is happening here, it's not just a question of the figure (which we already use on napari.org)—then using the side space better should be considered part of it. In fact, I'd say deciding the layout is more important than the contents and copy.
Also it is more or less how matplotlib and numpy homepages work: no ToC on homepage, ToC when you go into stuff. So if that was the motivation...

Edit: didn't see @Czaki post, sorry, but I'm in agreement.

[jni]

then using the side space better should be considered part of it.

Fixing the home page layout is a theme issue, not a docs issue, so indeed, out of scope for this PR. I'm sadly ill-qualified to deal with that. I have been investigating the mpl home page source, see here and here, and hopefully we can move to that soon. In the meantime I still think this change is worthwhile.

I'd prefer the newly shortened text to be above the figure?

Unfortunately, the choices given the current theme are, big-ass code block above the image, or tiny code below it. I mean, I can have just the tiny code in a code block, but imho that looks worse.

So, to clarify, I guess we want:

# napari: a multidimensional image viewer for Python

image
tiny code
bullet points
grid

or:

# napari

## a multidimensional image viewer for Python

image
tiny code
bullet points
grid

Or...?

But, again, to be clear, the overall layout is a much bigger lift that I think we should tackle separately. It will need a different build mechanism, maybe a different repo, and theme updates. I don't think we should wait to get all those ducks in a row to update our readme-style page.

[melissawm]

As a starting point, if you folks want to just get rid of the empty sidebar in the homepage, there is a way to do that from the conf.py file by adding

html_sidebars = {
  "index": [],
}

This however also removes the search bar from the home page, which I'm not sure we want.

For the formatting of the caption, if you prefer you can always use the {raw} directive, something like:

```{raw} html

<b>napari.imshow(cells3d(), channel_axis=1)</b>
```

and format directly (or create a new element in the custom.css file).

EDIT: I think this could only work outside of the figure caption, though. So this works:

```{figure} images/multichannel_cells.png
:name: multichannel-cells
:alt: napari viewer showing 3D cells image
:align: center
```

```{raw} html

<b>napari.imshow(cells3d(), channel_axis=1)</b>
```

[DragaDoncila]

I think this is 100% a big improvement over the current home page.

I agree that we want the "A multidimensional viewer for python" bit above the image. I would probably just add it to the main heading unless we can do a nice tagline.

I think we should format the caption as per Melissa's suggestions above, and yes we should definitely have a video not just a static image.

I agree we shouldn't get hung up on changing the layout in this PR.

[jni]

(b) I think the alt text is more prominent than the caption text because alt text is usually default styled as body link text. That's what it looks like to me here. Body text is typically styled to be larger than caption text.

This explains it indeed. I expect that the issue is that it's a movie and not an image and then different rules apply. Let's see if I can fix it with raw html...

[jni]

Bleurg, the grid also looks insanely awful on mobile... would be good to have a responsive design here, but I think that's hard/impossible with the existing syntax...

omg I tried to make it 1 grid with 6 elements instead of 2 grids of 3 elements each and the results are cursed 😂:

Screen.Recording.2023-03-01.at.10.48.23.pm.mov

[jni]

Here we go, using html5, providing videos in webm, mp4, and with a fallback jpg:

Can people please test on their mobile browsers? 😊

Given my comment above, I suggest we punt on the mobile column layout.

PS: @isabela-pf, indeed it turns out videos can't have alt-text 🤦, which explains why the formatting changed completely — there was no way to hide it in the video tag.

[melissawm]

The circleCI artifact is failing to load the video for me, otherwise it doesn't look too bad (chrome on Android)

[psobolewskiPhD]

Here we go, using html5, providing videos in webm, mp4, and with a fallback jpg:

Still broken on my Safari Desktop (13.2.1)

Play does nothing, whether I use the CircleCI preview or download the artifact and view locally.

Same issue on Chrome 110.0.5481.177 with CircleCI and downloaded artifact (black box with controls, but no working video).

Same behavior on Safari on mobile iOS 16.3.1 (using the CircleCI preview)

[psobolewskiPhD]

@jni in the downloaded artifact I don't see the tribolium files in _images, which is probably the problem.
Edit: in fact they are nowhere in the whole zip, so there's nothing to view. Same with the CircleCI--if you click open video in new tab, it returns error.

[jni]

Oh dang! It's because I'm not doing a clean build locally 🤦. Sphinx was putting the webm in there when I was using sphinx, but not now that it's raw html. But my code found it because the webm was there from a previous build. Gah.

@melissawm do you have any idea how I could mark files to get added to the build _images directory independent of them being referenced in a sphinx element?

[psobolewskiPhD]

@jni I think it may work if you use _static instead? Or just add them to another file somewhere to get sphinx to copy.

[jni]

_static is the ticket! Just checked with local clean build. 😊 Thank you!

[psobolewskiPhD]

Works good on desktop and mobile Safari on my end.

[Nadalyn-CZI]

I absolutely love the idea of having a video showing up on the home page. I would like to suggest that we use some colormap other than grey so it would show up even better.

[psobolewskiPhD]

@jni We discussed this PR in the docs working group.
It looks like the main hold up is the mobile tiles layout (see #102 (comment))
@kandarpksk pointed out the plausible data:
https://plausible.io/napari.org?period=year

It looks like we have <10% mobile visitors—which makes some sense, because people are likely to look at napari docs while having access to napari, so on their workstations, laptops, etc.

Maybe we can merge this and iterate on the theme issues? Need to find someone comfortable with handling the PR to the theme.
Also, per comment above, using a different color map could make it more eye catching, as long as there is good contrast on the black background. Not a blocker.

[jni]

@psobolewskiPhD it would be a big relief for me to get this merged (especially before 0.4.18), so if people are ok with it I think we should merge and then deal with colormap in future PRs. 🙏

[psobolewskiPhD]

@jni I'm going to approve.
In the CircleCI preview the gallery is broken, but the zip artifact is fine.
Would like @melissawm to take one more look to make sure her mobile issue is also resolved.

[jni]

Well spotted about "Napari", dunno how that got in there!!! 😅

[melissawm]

Works and looks great on Firefox/Linux and Android, you did it @jni!

[Nadalyn-CZI]

Bravo!

…

On Wed, Jun 21, 2023 at 2:29 PM Peter Sobolewski ***@***.***> wrote: Merged #102 <#102> into main. — Reply to this email directly, view it on GitHub <#102 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A3CMNTGX7WXPE2ETCAMBI2DXMNDSNANCNFSM6AAAAAAUNT5G5U> . You are receiving this because you commented.Message ID: ***@***.***>

-- Nadalyn Miller 214-906-5489 personal cell