DOC: Update front page of documentation with Sphinx-Panels

[MarsBarLee]

Addresses #18419: Hard to navigate docs front page

I'm working with @rossbar to implement the following changes:

• Remove html templates
• Remove references of html templates
• Add sphinx-panels as a extension
• Replace index.html/Documentation front page with index.rst
• Update the Overview page, following this mock-up
• Create the Getting Started page, which includes brief installation instructions and links to various guides, depending on user profile (Absolute Beginners, F2P, etc) -> This change will be in a future PR instead

[MarsBarLee]

Why remove the html templates?

• currently, both rst and html is used
• the html templates over-ride the PyData theme, which creates visual insistencies and accessibility issues
• by keeping to rst, we maintain consistency and reduce unnecessary cross-reference to other file types

[melissawm]

The CI failures have nothing to do with your PR, it builds successfully locally. I think this has to do with a recently merged submodule #19478

[melissawm]

There seems to be a quality issue in some images though:

Also, I think the images should not be under the neps folder, they should probably be under doc/source/_static

[rossbar]

The CI failures have nothing to do with your PR, it builds successfully locally. I think this has to do with a recently merged submodule

Indeed, nice catch @melissawm . The unfortunate consequence of this is that the CircleCI build (which is used for doc preview) won't work. The easiest way to fix this would likely be to merge (or rebase, if you're comfortable, though this will require some manual conflict resolution) main into this branch.

[MarsBarLee]

Thanks @melissawm and @rossbar!

I've had problems previewing the SVGs used in the panels with LiverServe preview on Gitpod. PNGs in the panels work fine. I can't build locally since I use Windows. So SVG preview could be a LiveServe problem specifically.

I think the sizing problems are due to the images automatically filling the whole panel.

However, I can work around it by previewing in another image type (such as PNG) and using that to specify the dimensions. Then in my final commit, push as SVGs with the image dimensions. And change the folder used to doc/source/_static.

For fixing the CircleCI build, could we do the merging or rebasing after the image changes?

[MarsBarLee]

Hi all, the a working version of the front page is now up! The various links work. However, the Getting Started page is incomplete right now, as a sphinx orphan page. Therefore this is more of a MVP as of now.

However, there's been errors on CircleCI build specifically- I may need to rebase or update versions.
TypeError: _argmin_dispatcher() got an unexpected keyword argument 'keepdims'

Here's the visual for those who can't yet see the update due to the CircleCI error.

Once the CircleCI works, it should be easier to see how the pages are connected and the user story flow.

There are some other upcoming changes to make in a future PR, such as shrinking the size of the images (which has been a little fiddly since SVGs size differently than usual PNG). There's also been suggestions to change the how some content is organized, such as for F2Py in #18419.

[MarsBarLee]

Hi all, this is ready to be merged. There were also some typos in my earlier screenshots that have been fixed.

As discussed in the Community and Docs meetings, this can be merged before the late December version release.

Builds on CI (best viewed in a non-Chrome browser, such as Firefox- images will not fully load on Chrome) so you can preview how it works.

As of now, this visual re-design does not apply the whole site. It will replace the current 'NumPy v1.21 Manual' as the front page of the docs. Therefore only the front page of the docs has sphinx-panels implemented.

In a future PR, there will be a new page, the 'Getting Started' that will include brief installation instructions and links to various guides, depending on user profile (Absolute Beginners, F2P, etc). This page will also have sphinx-panels.

The panel 'User Guide' links to the current User Guide page.

The original plan was to implement this visual change to multiple pages at once- however, I realized that process would take a long time without other people able to see or comment for feedback easily. So instead it will be implemented page by page, but a big picture overview is available in the interactive mock-up.

These different pages will eventually visually unified, but the main function of the front page is retained.

[melissawm]

If I remember correctly, the plan is to have the getting started button point to this page, and list the absolute beginners and quickstart under this, right?

[MarsBarLee]

Yup! The Getting Started page is currently an orphan page. It will be fleshed out in a future PR.

[melissawm]

Thanks @MarsBarLee ! I don't see any blockers at this point, any refinements can be done in a follow-up. LGTM!

[charris]

Thanks @MarsBarLee .

[charris]

@MarsBarLee I hope you did not need anything from the merge of main, because I had to skip it for the backport. Generally speaking, main should not be merged unless there are conficts, and if there are conflicts, a rebase if preferred.

[charris]

@MarsBarLee I note that graphics for "Getting Started" and "API Reference" are missing. Is that deliberate?

[MarsBarLee]

Hi @charris, when building in CircleCI, there was a problem viewing the images in Chrome but no problem with other browser such as Firefox. I assumed this was a CircleCI specific issue.

However, the problem may persist across Chrome browsers locally and in the release. It may be how Chrome displays different SVGs.

I'll do some more cross-browser testing and make a PR to fix it CircleCI, so hopefully it's fixed elsewhere. Should I make a clone of the numpy:maintenance/1.22.x branchfor this? Or clone this branch from this PR?

[charris]

@MarsBarLee Make a PR branched from main, that is where everything in NumPy starts. After the fix is merged I will backport it. I put the original PR in 1.22.x so that any fixes that went into main could be easily backported. It would be nice if there was a fix before the release of 1.22.0 at the end of the month.

[MarsBarLee]

@charris OK, thank you! Based on my current research it looks like a simple fix, so if it is, it can be done before the end of the month.