[kohlerca]

This PR introduces some fixes and improvements to display citations and bibliography in the Elephant documentation.

In the documentation pages, citations use the "Author, Date" format. However, some bibliographic references are displayed ambiguously, as there is more than one citation for the same first author in a given year (e.g., Grün et al., 2002, in the Unitary Event Analysis documentation). This is also noted with warnings when building the documentation with Sphinx. The ambiguous labels are present both in the bibliography list and in-text citations.

The first fix in this PR updates the bibliography label formatter used with Sphinx, which is currently based on BaseLabelStyle. This was changed to inherit from AlphaLabelStyle that already disambiguates labels for repeated years. This is complemented by extending the custom formatter for in-text citations to also handle the year part of the labels together with the round brackets.

Another issue is that some bibliography labels are rendered showing LaTeX escape characters (e.g., Gr{\"u}n, 1999). The second fix changes the label formatter to process the escaped text.

The third fix removes build warnings regarding duplicated bibliography entries. The reference for Stella et al., 2019 is used both in the citation.rst source file and in the docstrings producing the documentation for SPADE. However, the citation keys are distinct between the files, and the reference is duplicated in elephant.bib, leading to the duplication warning. The redundancy was removed and the affected citation directives :cite: fixed.

Finally, docstrings were revised to use :cite:t: directives for textual citations instead of existing :cite:, avoiding mixing parenthetical citations with prose text (i.e., instead of "see (Author, Year) for ...", use "see Author (Year) for ...", together with minor formatting fixes for readability. A new reference Babin2012_7 was added as a consequence of using the new commands.

[coveralls]

coverage: 88.242% (-0.4%) from 88.605% — INM-6:fix/documentation_citations into NeuralEnsemble:master

[CozySocksAlways]

Apart from the nitpicks, this looks good to me.
CI's should work fine once #721 and #722 are in.

[mdenker]

Great job at this, looks really good. There is one potential improvement in simplifying the alternate label generation in conf.py, which came out of an AI conversation on that code. Please have a look if the alternate suggestion is better, otherwise this PR is good to go.

[mdenker]

In conversing with AI, there was a suggestion to change this code to call the direct constructor of the superclass, instead of GroupReferenceStyle.post_init, and later extending the custom styles. The reason given was that in the current implementation, AuthorYearReferenceStyle.post_init is skipped, and therefore :cite:author:, :cite:year:, and others will not be available (although currently not used in Elephant, they may be in the future).

I would suggest to try out his little change, and if it works, keep it -- it looks cleaner, and promised more functionality (although I am not sure if there would be more changes needed to this file to make something like (cite:year: work...). If not, there is nothing wrong with the current implementation (except that is breaks the citation formats listed above).

def __post_init__(self):
super().__post_init__()  # keep all default author-year roles
custom = [
DisambiguatedParentheticalStyle(...),  # arguments unchanged
DisambiguatedTextualStyle(...),
]
self.styles.extend(custom)
self.role_style.update(
(role, style) for style in custom for role in style.role_names())

[mdenker]

Is there a functional reason for the assert? If so, would an if statement be better?