Updated docs with community section

[niksirbi]

The Community section

I updated the movement docs to add a new "Community" section.
It could also be called "About", but I prefer the "Community" term (borrowed from napari docs).

This section includes:

• A community landing page, with links to the parts below and contact info
• the statement on mission, scope, and design principles.
• the roadmap
• the contributing guide (it was a standalone page before, now I have moved it within this section)
• Related projects
• License (included from the file in the repository)

Many thanks to @adamltyson, @lochhh and @sfmig for helping me draft the mission, scope, design principles and roadmap!

Accompanying changes

The docs landing page and the repo README have also been updated to reflect the new structure of the docs. There is an "Overview" section in both, which contains the text @adamltyson wrote for the neuroinformatics main website. There is some regrettable repetition between these two documents (violating DRY), but including content from one of them to the other creates some nasty formatting issues (due to syntax differences between GitHub and Sphinx-Myst markdown). I think some repetition is fine for now, unless we want to write a GitHub action for building the README file automatically. Some links in the README will not work because they lead to the new website pages (which have not been deployed yet), but this should be fixed after merging and releasing.

I also was tempted to include some small docs fixes, e.g. changing the copyright holder to UCL, and making the URL for some pages more sensible.

What is missing from the Community section

• A section about the core project members? Similar to this napari page. It should also mention NIU, SWC, etc.
• A funding section
• A contributors page, thanking everyone, similar to the brainglobe one
• A governance page (we don't absolutely need one now, but we may need it soon)
• The "Related projects" section needs to be fleshed out as per Expand on "Related Packages" in the README. #58

How to review this PR

The best way is to build the docs website locally, following these instructions.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (1d4aba5) 98.05% compared to head (5b24fc7) 98.05%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #72   +/-   ##
=======================================
  Coverage   98.05%   98.05%           
=======================================
  Files           8        8           
  Lines         308      308           
=======================================
  Hits          302      302           
  Misses          6        6           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[adamltyson]

LGTM! 🎉

[lochhh]

Great work! 🚀

[niksirbi]

This error in building the docs took me forever to track down, but I now know its source.
Strap in, because it's a loong story:

Because our documentation includes examples built with Sphinx-Gallery, movement itself has to be included in docs/requirements.txt. This is achieved by adding -e . at the top of that file. So far this worked fine.

However, movement depends on sleap-io, which in turn depends on PyAV - a package providing Python bindings for ffmpeg. PyAV, which is available on pip as av, doesn't (yet) provide wheels for Python3.12.

Normally, this wouldn't be a problem for us, since we officially support Python versions 3.9 - 3.11. That said, the reusable workflow we use for building the Sphinx docs includes:

  - name: Setup Python
    uses: actions/setup-python@v4
    with:
      python-version: '3.x'

3.x means the latest stable version, and must have recently been changed to 3.12. So when this action runs, it tries to install movement -> sleap-io -> av in a Python 3.12 environment, and fails to find the wheels. I reproduced this locally on Ubuntu. The documentation build would fail on 3.12 and succeed on all previous versions.

We could solve this in a number of ways:

• Modify the reusable Sphinx build action to use Python 3.11 (instead of the latest). This is probably the easiest option. Or even better, expose a Python version option for this workflow, so it can be flexibly chosen depending on the package.
• Ask sleap-io developers to switch their dependency from PyAV to pyav - which is a recent fork and provides the right wheels. But this may be unnecessary and rushed, if we assume that PyAV will eventually add the wheels.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[niksirbi]

I solved the issue by updating the GitHub action and running it with Python 3.11. Thanks @alessandrofelder for approving the action update. Merging now.