Documentation page: mkdocs & GitHub pages

[mknorps]

In this PR, a documentation page using mkdocs and deployed on GitHub pages is added.

Documentation content

Documentation page is based on the content available in the current README.md file. The content is split and grouped according to diataxis principles to provide explanations, usage guide and FAQs for FawltyDeps.

To build documentation, mkdocs with mkdocs-material are used due to simplicity and wide support.

Deployment

Documentation page is deployed on GitHub pages (see Settings -> Pages) and is using the content of gh-pages branch.
Content of gh-pages is automatically created with GitHub Action, following the documentation of mkdocs-material.

Local tests

First, install docs dependencies:

poetry install --with docs

Then build and serve locally:

mkdocs build
mkdocs serve

[jherland]

Big review, lots of comments, but don't be discouraged! I love the look of the docs website, and I'm happy to help in any way I can to get this merged! ❤️

[jherland]

Thanks for updating this part. I think it should be updated to reflect that v3.8 is actually EOL, but we still intend to support it for now:

- Support all current Python versions: that means [all Python versions that have
  a stable release, and are not yet End Of Life](https://devguide.python.org/versions/).
  - We also try to support older (EOL-ed) Python versions, when doing so is not too expensive.
  - Currently we support running on Python v3.8 - v3.13.
  - Since we no longer rely on running inside the same Python environment as the project being
    analyzed, it is possible for us to support analyzing projects running on even older Python versions.

More generally, this file is starting to show its age (e.g. the sentence about Windows below), and would benefit from another pass to make it more up-to-date (not in this PR! 😅).

[jherland]

After some more thinking, and our discussion on Slack I'm ready to change my mind on this: We only aim to support running current versions of Python, and improving support for older projects should be done via solutions outlined in #460.

Suggest:

- Support all current Python versions: that means [all Python versions that have
  a stable release, and are not yet End Of Life](https://devguide.python.org/versions/).

Or feel free to leave the patch as is and resolve this thread.

[mknorps]

How about this as a compromise:

- Support all current Python versions: that means [all Python versions that have
  a stable release, and are not yet End Of Life](https://devguide.python.org/versions/).
  - Currently we support running on Python v3.8 - v3.13.
  - Since we no longer rely on running inside the same Python environment as the project being
    analyzed, it is possible for us to support analyzing projects running on even older Python versions.

Without the promise of supporting the older versions, but gives hope that the user can check the code written in the older Python version anyway.

[jherland]

Ship it 😄

[jherland]

I took another look now, and except for two open questions (#449 (comment) and #449 (comment)) I think this is ready to get merged. 🎉

I also notice that the preview of the documentation page on https://tweag.github.io/FawltyDeps/ does not appear to be updated with the latest changes (for one, the menu structure on the left-hand side does not reflect the nav structure in mkdocs.yml).