Skip to content
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

docs: Restructure, add tour, add sidebar links to package docs #26

Merged
merged 2 commits into from
Mar 28, 2025

Conversation

aaron-hopkinson
Copy link
Contributor

@aaron-hopkinson aaron-hopkinson commented Mar 28, 2025

  • Restructure the overview/package descriptions sections including:
    • Having a single description of Anemoi on the homepage (+ the package diagram)
    • Package descriptions moved to a separate page
    • Package dependencies moved to package description page rather than the homepage
    • Moved install instructions to their own page
  • Added "A tour through Anemoi" page, linking to detailed docs following "user journey" discussions
  • Misc small tweaks:
    • Add links to external packages (PyTorch, earthkit etc)
    • Small wording tweaks to improve clarity
    • Added alt-text to figures for accessibility
    • Links to other anemoi package docs on sidebar to improve navigability

📚 Documentation preview 📚: https://anemoi--26.org.readthedocs.build/en/26/

VeraChristina
VeraChristina previously approved these changes Mar 28, 2025
Copy link
Contributor

@VeraChristina VeraChristina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! Clear entry points to different parts of the ecosystems, and it generally looks much cleaner.

Two comments (that are probably out of scope for this PR):

  • the figure on the landing page is difficult to read, and slightly biggerer figure/higher res would help a lot
  • the "anemoi training getting started" link points to the user journey in the training docs, which is not really a quick start entry point. (I don't think there is a better point to link to currently, hence out of scope)

@aaron-hopkinson
Copy link
Contributor Author

Thanks @VeraChristina

  • Re: image on landing page – I just increased the size of the image. Hopefully that helps.
  • Re: training quickstart – it looks like the Docathon training PR has been merged (docs(training): Docathon anemoi-core#201), so unless there's something else in flight, I suspect it's probably fine to merge this and then pick that up with the training docathon group. What do you think?

Re: images – The source currently has inlined raw HTML which I think would be better replaced with an rst figure directive, especially since the HTML currently has a <center> tag (which was deprecated back in HTML4, and is obsolete in HTML5, afaik). However, the embedded HTML does seem to use both object and img elements, which I think might be intended to support fallback from SVG to PNG versions of the images, which wouldn't be supported by the (arguably cleaner) rst version. However, I think all modern browsers support SVG, so we should probably just use this version. (Plus I don't know how well the fallback works – and using object over img seems less semantically clear, but I'm not a web developer...). Maybe one for a follow up PR, what do you think?

@VeraChristina
Copy link
Contributor

Thanks a lot!
Re: image size -- yes, it's much more readable
Re: training quickstart -- I agree, let's pick this up separately with the training group
Re: raw HTML vs rst figure directive -- same here, let's pick this up separately

@aaron-hopkinson aaron-hopkinson merged commit b327f1a into main Mar 28, 2025
6 checks passed
@aaron-hopkinson aaron-hopkinson deleted the docs/restructure_add_tour branch March 28, 2025 15:23
@github-project-automation github-project-automation bot moved this from Now In Progress to Done in Anemoi-dev Mar 28, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

2 participants