Enhancements to Documentation Structure and Theme Upgrade

[Fanchengyan]

The main modifications to the documentation include:

1. Improved the document structure by dividing it into functional modules, enhancing searchability and readability.
2. Changed the document theme from sphinx_rtd_theme to pydata_sphinx_theme, resulting in a more visually appealing and elegant documentation.
   1. Two themes are available for selection: black and white.
   2. Utilized both the left and right spaces (Section toc and Page toc), facilitating users in finding desired content.
   3. keep in line with the matplotlib documentation.

[raphaelquast]

Hey, thank you very much for your contribution to EOmaps! Highly appreciated!

I've already been thinking about moving to the PyData theme as well for quite some time now but never managed to find the time to actually give it a try... really curious to see how the docs look with this theme!
Screenshots already look really nice!

Some initial comments from my side before I can review your changes:
I see that you have commited all the files from the API docs (e.g. files in the "generated" folder) which is why there are now 647 changed files... Those files are auto-generated by sphinx-autodoc on each build and should not be part of the source-code (they would be overwritten during the build-process anyways).

Could you please remove those files from your PR? It would make it a lot easier to review your actual changes.
(The top-level .gitighore file should actually avoid that files in the generated folder are commited... )

Also... what is the purpose of this GitButtler Integration Commit?

[raphaelquast]

Tests are currently failing due to code-style issues reported by pre-commit.

Can you please run pre-commit to auto-format your changes so that they comply with the used code-style?
You can find instructions on how to use pre-commit in the docs: contribute - style-cecking. Thanks!

[Fanchengyan]

OK, I'll revise it again soon.

[Fanchengyan]

It should be fine now. The documentation can be previewed at: https://eomaps--249.org.readthedocs.build/en/249/index.html

[raphaelquast]

Awesome! It looks amazing 🤩
However, the "docs/generated" folder is still part of the PR so there are still 649 changed files... can you please remove it so that the auto-generated API docs are not part of the repo? Thanks!

Once this is done I'll try to find some time as soon as possible to do a proper review of the changes to see if all looks (and works) as expected.

Again, thanks a lot for your efforts here!

[Fanchengyan]

I added a commit that deleted the generated folder. The compilation of the document itself shouldn't be a major issue, but there are two problems that may need further resolution:

1. I've only done an initial restructuring of the document, and it may need further additions/modifications to some content. For example, some newly added items in the header don't have emojis, and some section index.rst files may need additional content to guide users into specific subsections.

2. Because the structure of the document has changed, the content in the test section may need to be updated accordingly.

[Fanchengyan]

Hi @raphaelquast

I've modified the pytest code related to the docs section, and it's now running properly. There should be no issues now. This is my first pull request, so the number of iterations might be a bit high. If there are any other problems, please let me know.

[raphaelquast]

I've only done an initial restructuring of the document, and it may need further additions/modifications to some content. For example, some newly added items in the header don't have emojis, and some section index.rst files may need additional content to guide users into specific subsections.

Yes, I agree... since this is quite a major change to the appearance of the docs, there are certainly a few additional changes required to make everything look and work as expected.
However, I believe that this is a good way forward and the docs will be much easier to navigate if this is done properly (... and the dark-theme switch is nice!)

I've modified the pytest code related to the docs section, and it's now running properly. There should be no issues now.

Great, thanks!

This is my first pull request, so the number of iterations might be a bit high. If there are any other problems, please let me know.

No worries on the iterations! Good thing takes time and we're all working in our free-time here.
If we go forward with switching to the pydata-theme I definitely want to do it properly!

I am happy to assist with this PR as much as I can until it's ready to be merged!

[raphaelquast]

I did a first quick review and so far most of the chapters look OK and the overall appearance and usabilty is very nice!
Thanks again for pushing this forward!

---

Please remove the docs/source/api/autodoc_additional_props.rst file as well (it is also automatically created during the build-process and should not be part of the repo). After that the tests should finally succeed.

---

And here's a list of suggstions I think would be nice to have... let me know what you think!

• The logo on the titlepage somehow has a white background in the dark-theme... can you make that transparent?

  

• There seems to be a mixup with the sectioin header levels in the sidebar

  

• Is it possible to remove the gray background color for the shapes-grid on the titlepage ?

  

• The User Guide already works really nice.
  However, the sections "Installation", "Examples", "API Reference" and "FAQ" somehow act like "standalone files" with an empty "Section Navigation"... Is it possible that they are part of the section hirachy?

  

[raphaelquast]

... and one general question:
I see that you allow changes by maintainers for this PR. Is it OK for you if i push changes directly to this PR (e.g. the associated branch of your fork) or would you prefer if i suggest edits as separate PRs to your fork?

[Fanchengyan]

I'm comfortable with both. This is my first pull request, and I'm still getting familiar with the workflow of pull requests. Currently, I'm in the process of refactoring the example section, taking inspiration from matplotlib. Once I'm done with the modifications, I'll push all the changes together.

[raphaelquast]

Ok, perfect! Dont hesitate to get in touch if you have any questions or need help!

[Fanchengyan]

Hi @raphaelquast

In this version, I switched myst-sphinx-gallery from pip to conda and pinned the version to 0.2.2. This way, even if there are issues with subsequent updates, it won't affect this library. Besides, I have added two new feature to myst-sphinx-gallery in version 0.2.2:

1. It now will print the time taken in the generation of the gallery and thumbnails. This helps to identify any performance bottlenecks in the gallery generation process.
2. I have added a new configuration to limit the maximum number of frames for the thumbnails. This helps to reduce the total time taken to generate the gallery to about 7.5 seconds in my computer.

Additionally, I made some adjustments to the documentation style of EOmaps to make it more visually appealing:

• Changed the default font size to 17px, since the default font size of pydata-sphinx-theme is a bit small.
• Adjusted the gallery style for better aesthetics:
  • Added margins to thumbnails so that they don't stick to the card border.
  • Reduced the font size of the image descriptions and changed the color to black.

Finally, I still recommend using myst-sphinx-gallery because I've added many new critical features based on the previous code. For instance, previously, I just simply referenced the example images directly, which had two issues:

1. Inconsistent image proportions: some images are very long while others are quite wide, making the page look unappealing.
2. Large image sizes: original images are very large, which could slow down the loading speed of the gallery page quite a bit. This will be more significant when adding more examples to the gallery in the future.

myst-sphinx-gallery, however, can automatically generate thumbnails to a consistent small size (Default: (320, 224)), enhancing visual appeal and ensuring optimal page load speed. Besides, it can easily customize the appearance of the gallery and thumbnails using a variety of configuration options.

[raphaelquast]

Hey @Fanchengyan
sorry for my late response!
I'm really grateful and amazed by your work here! Nice to see that you already managed to put myst_sphinx_galery on conda-forge!

After consideration of your comments I agree that using myst_sphinx_galery provides a lot of benefits compared to the current approach and I'm happy to use it in EOmaps!

I checked your changes and added some minor comments in the code.
In addition, I noticed the following issue:

• Your change to make the image-descriptions black does not work well with the dark-theme...
  Can you set the color to white in case the dark-theme is active?

And finally, since none of your code should affect the baseline images for the unittests, can you please remove the updates to the tests/baseline folder from the PR?

Thanks again for all your work here! The new docs look amazing!

[raphaelquast]

Oh and a design question/suggestion...
I think the emojis in the header are not particularly nice... I'd suggest to remove them. What's your opinion on this?

[raphaelquast]

Perfect! The landing-page looks much cleaner now!
From a first quick look this seems to be ready to be merged! 🥳

Any pending changes from your side still?

[Fanchengyan]

This PR looks fine to me now. However, I have a broader suggestion:

Consider duplicating some key examples from the User Guide in the Example Gallery in the future. This would make it easier for users to find relevant examples quickly. In my experience with matplotlib, I often directly search in the examples rather than in the User Guide. User Guide can be linked to each example for users who need more detailed information.

[raphaelquast]

This PR looks fine to me now.

OK nice! Then I'll try my best to merge this as soon as possible and then release a new version including some other pending changes/fixes!

Consider duplicating some key examples from the User Guide in the Example Gallery in the future. This would make it easier for users to find relevant examples quickly. In my experience with matplotlib, I often directly search in the examples rather than in the User Guide. User Guide can be linked to each example for users who need more detailed information.

Yes, I fully agree on that part... I hope to find some time in the future to also extend the galery to include both more simple examples that just show a specific feature as well as extensive examples showing how far you can go with EOmaps.
The new galery is definitely a big step forward to make this a reality since the thumbnails now allow having a lot of images in the galery without slowing down the browser too much!

[raphaelquast]

Hey, I made some minor adjustments to fix remaining issues:

• Updated dependencies to latest versions

• Fixed remaining sphinx-build warnings

• Fixed decrease in code-coverage due to no longer tested examples and doc-codeblocks

  All code-blocks found in the documentation that have a tag ":id: test_...." are automatically parsed and run as unittests.
  The re-structuring of the docs broke this since previously it was assumed all source files are in the same folder.
  The same is true for the examples (.py files have previously been used to auto-generate unittests for each example)
  Now a recursive glob-pattern is used to ensure all files are properly checked for codeblocks.

[raphaelquast]

I did some more re-structuring and fine-tuning of the docs:

• Removed left/right sidebar on pages where they are not needed
• Removed intermediate pages from the User guide in favor of a richer landing-page
• Shortened all titles as much as possible so that most of them fit properly in the sidebars
• Fixed some issues with the auto-generated pages for the "reader" methods
• Re-structured the API docs landing-page a bit to make it less crowded

I think with those final changes the new docs are ready to be released!

Thanks again for all your work here! It really helped to make the docs a lot better!

[raphaelquast]

Its done! 🥳
Big thanks for all your efforts here! Hope we can collaborate again in the future!