Add citation tool

[willGraham01]

Docs PR is against website : brainglobe/brainglobe.github.io#146

brainglobe/BrainGlobe#61 gets closer to being resolved.

Would recommend reading the docs PR before the source code 😅

TLDR; on the command line you can now ask BrainGlobe to cite itself:

$ cite-brainglobe brainglobe atlasapi
@article{bg-atlasapi,
    authors = "Federico Claudi and Luigi Petrucco and Adam Tyson and Tiago Branco and Troy Margrie and Ruben Portugues",
    title = "BrainGlobe Atlas API: a common interface for neuroanatomical atlases",
    journal = "Journal of Open Source Software",
    year = "2020",
    volume = "5",
    month = "10",
    doi = "10.21105/joss.02668",
}

@software{brainglobe-meta,
    authors = "BrainGlobe Developers and Wiliam Michael Graham",
    title = "BrainGlobe",
    url = "https://brainglobe.info/",
    year = "2024",
    abstract = "The BrainGlobe Initiative exists to facilitate the development of interoperable Python-based tools for computational neuroanatomy.",
    license = "BSD-3-Clause",
}

The output can be redirected to a file if the user so chooses. Other CLI options:

$ cite-brainglobe --help
usage: cite-brainglobe [-h] [-l] [-s] [-w] [-o OUTPUT_FILE] [-f FORMAT] [tools ...]

Citation generation for BrainGlobe tools.

positional arguments:
  tools                 BrainGlobe tools to be cited.

options:
  -h, --help            show this help message and exit
  -l, --list            List citable BrainGlobe tools, and formats, then exit.
  -s, --software-citations
                        Explicitly cite software source code over academic papers.
  -w, --warn-unused     Print out when citation information is omitted by the chosen citation
                        format.
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output file to write citations to.
  -f FORMAT, --format FORMAT
                        Citation format to write. Will be overwritten by the inferred format if
                        the output file argument is also provided. Valid formats can be listed
                        with the -l, --list option.

What's it doing?

The brainglobe_utils.citation module fetches CITATION.cffs from each repository that we tell it about, parses this information into the requested format, then spits it out.
Currently supports:

• Text, or "just a sentence for citing" as per Add a recommended citation sentance to repos BrainGlobe#61
• BibTex format

The text field supports the custom "citation-sentence" field that we want to use for BrainGlobe tools. Annoyingly, we can't just query the github api to do this forwards (the part that writes outputs is not public yet) nor can we use other existing tools like cffconvert (because they complain if we have extra fields that are otherwise harmless).

How will it be maintained?

So long as each of our repositories has a CITATION.cff (or otherwise equivalent file), and the citation module is informed of this, details will be fetched correctly even after updates to the tools themselves.

[codecov]

Codecov Report

Attention: 53 lines in your changes are missing coverage. Please review.

Comparison is base (13d0444) 74.55% compared to head (d97fe3e) 76.42%.
Report is 6 commits behind head on main.

❗ Current head d97fe3e differs from pull request most recent head 0a24726. Consider uploading reports for the commit 0a24726 to get more accurate results

Files	Patch %	Lines
brainglobe_utils/citation/cite.py	43.02%	49 Missing ⚠️
brainglobe_utils/citation/repositories.py	96.05%	3 Missing ⚠️
brainglobe_utils/citation/format.py	97.77%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #28      +/-   ##
==========================================
+ Coverage   74.55%   76.42%   +1.86%     
==========================================
  Files          25       31       +6     
  Lines         849     1141     +292     
==========================================
+ Hits          633      872     +239     
- Misses        216      269      +53     

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

[alessandrofelder]

Looking really good @willGraham01 - code is expressive and easy-to-read.
Have a few minor comments - mostly typos.

[adamltyson]

Can this be merged?

[willGraham01]

Can this be merged?

If you're happy with it's current state, yep. I've started my own dev branch to incorporate these features that'll build on top of this.

[adamltyson]

@alessandrofelder seems happy, so LGTM.