Use `DocumenterCitations`

[goerz]

In the context of openjournals/joss-reviews#8545:

The documentation of Antique cites a number of papers. It would probably benefit from using the DocumenterCitations plugin to do this. Full disclosure: I am the maintainer of that package.

This is just a recommendation, certainly not a blocking issue for publication in JOSS ;-)

If you need help setting up DocumenterCitations, let me know.

[lhapp27]

Thank you for your comment (and for the package!). I have used DocumenterCitations.jl in the documentation of my own package before, and I agree that it is very convenient for managing references.

@ohno: do we have a complete .bib file of all the references? I think that would be required.

[ohno]

@goerz
Thank you for introducing the package. I completely agree that citations should be managed via a .bib file and associated tooling. We are open to rewriting both the docstrings and the documentation accordingly.

I have one question: is it possible to display the citation information within the docstring itself? If your package supports citation display directly in the docstrings, we would be happy to install and adopt it right away. Please let us know if there's a recommended workflow or best practice for doing so.

My philosophy is that code, mathematical definitions, and bibliographic references should be located as closely as possible. For that reason, our current implementation includes references directly in the docstrings—see this example. If this design is not compatible with DocumenterCitations, we’re happy to move the definitions and references to the documentation instead.

@lhapp
Since you have experience using this package, could you install DocumenterCitations? Please create tentative bib file. I will add the references later. I think the branch name should be doc/90.

[goerz]

is it possible to display the citation information within the docstring itself?

In principle, yes, as discussed in "Citations in docstrings".

In your example, since you would be making extensive use of notes like "p.595 (a.4), (a.6)", you might experiment with using @citet or @citet*, or, else, using complete custom strings as recommend in "Citations in docstrings".

I've had some thoughts about adding a @citefull feature to DocumenterCitations that would render not just the author name like @citet, but a minimal but complete citation. That could be useful here, but I'm probably not going to add this feature in the very near future.

[ohno]

@goerz Thank you again. I appriciate your generous support. This package suits our purpose.

@lhapp27 As we talked before, please install DocumenterCitations. Please create branch doc/90 and apply it to the docstrings of https://ohno.github.io/Antique.jl/stable/DeltaPotential/ at the first.

Please share with @ajarifi as necessary and apply it to the model below.

• https://ohno.github.io/Antique.jl/stable/InfinitePotentialWell/
• https://ohno.github.io/Antique.jl/dev/MorsePotential/
• https://ohno.github.io/Antique.jl/stable/PoschlTeller/
• https://ohno.github.io/Antique.jl/stable/RigidRotor/
• https://ohno.github.io/Antique.jl/stable/InfinitePotentialWell3D/
• https://ohno.github.io/Antique.jl/stable/SphericalOscillator/
• https://ohno.github.io/Antique.jl/stable/CoulombTwoBody/

I will sort out the references of

• https://ohno.github.io/Antique.jl/stable/HarmonicOscillator/
• https://ohno.github.io/Antique.jl/stable/HydrogenAtom/

[lhapp27]

I have pushed the branch doc/90 now. It contains the updated make.jl and the refs.bib. The docstrings for DeltaPotential, PoschlTeller and InfinitePotentialWell3D are already updated.

One thing to note: In the PoschlTeller docs I removed one link to "archive . org". I am not certain about the legality of all contents of this website, so I'd rather not distribute their links via our package. If you are certain about it, feel free to put the link back in.

[lhapp27]

I updated the references for all models besides HarmonicOscillator and HydrogenAtom, and pushed to the branch doc/90. For the SphericalOscillator, one reference was a dead link (beit.tech). I could not recover their blog post, hence I removed the reference.

[ohno]

@lhapp27
Thanks for your contribution.

I agree that archive.org is not exactly legal, and sometimes links break, like SphericalOscillator. Going forward, we do not display links because it's enough if the document has a DOI.

I created pull request #104. There is a bug with the deployment of the documentation. I will fix it when I commit my local changes for HarmonicOscillator and HydrogenAtom.