Add Documentation for average_precision() and mean_average_precision() Workflows

[axiomcura]

About this PR

This PR introduces documentation (mention in #71) for the functions associated with the average_precision() and mean_average_precision() workflows. The primary goal of these docstrings is to provide users with a clear understanding of how these functions process data and the logic behind them. I’ve aimed to make the explanations as abstract and user-friendly as possible, allowing users to easily follow the workflow without requiring deep familiarity with the underlying code.

In particular, I would appreciate feedback on whether the explanations for the parameters pos_sameby, pos_diffby, neg_sameby, and neg_diffby are clear and effective. I feel that these parameters are critical to understanding and effectively using the average_precision() and mean_average_precision() functions, so ensuring their clarity is essential.

Use mkdocs for generating a documentation page (potential future contribution)

Additionally, I recommend using MkDocs for generating and hosting the documentation on GitHub Pages. MkDocs provides a simple and effective way to turn docstrings into a readable and structured website. Since the docstrings follow the NumPy format, they can be seamlessly integrated into a documentation-style webpage using plugins like mkdocstrings-python. This plugin can automatically extract docstrings from functions and format them in an organized manner, making the documentation more accessible and professional.

If you find the idea of using "mkdocs" appealing, I’d be happy to take the lead on implementing it.

[alxndrkalinin]

Awesome! One thing that immediately came to attention is that we're still aiming to support Python 3.8, so we use typing module for generics annotations (PEP 585 was introduced in 3.9), that's why check s failed.

Are you planning to document all functions with docstrings before we merge?

We will update the wiki this week, so you can see tutorials that are already developed.

[axiomcura]

Yeah, I noticed that as well, I completely forgot that Copairs still supports Python 3.8. That’s an easy fix, though.

Are you planning to document all functions with docstrings before we merge?

The focus of this PR was primarily to document what AP and mAP do, as our lab is starting to use mAP more frequently. Since there’s no existing documentation, I took the initiative to document all relevant functions related to AP and mAP so that others can better understand their usage. So the answer is no for other functions in this PR.

I’m not too familiar with the other functionalities that Copairs offers, but I can try to help where I can. One suggestion would be to set up MkDocs for the module so that the documentation can be a collective effort. This way, contributors with a better understanding of the other functions can submit PRs to document them.

To streamline this process, I’d also recommend creating a contributions.md file. This would provide clear guidelines for contributors on:

1. Documentation style, format, and expectations.
2. Steps to test their changes by hosting the MkDocs server locally.

We will update the wiki this week, so you can see tutorials that are already developed.

Great! exciting to hear!

[axiomcura]

Hi @alxndrkalinin!

I wanted to provide you with a quick update! I’ve successfully updated the type hinting to support Python 3.8. However, I’m encountering some issues with the tests. After reviewing the changes I made, I noticed that none of the existing codebase was modified in a way that should cause these errors. I was wondering if this was expected since you are actively doing some changes to the code base.