Document standalone citation processing

[agitter]

The Manubot package can be broadly useful for citation processing even if users do not need the full functionality. We could document how to map citation identifiers to CSL JSON items with standalone examples like the test cases in test_citations.py.

See greenelab/deep-review#886 for another potential use case.

[slochower]

Do you mean harnessing the citation facility within Manubot without the full GitHub and CI functionality?

I have a little script locally that'll take a Markdown file I'm writing, copy it somewhere (e.g., /tmp but it doesn't really matter), run Manubot to process the citations, and then copy it back or display in browser. This way I can use Manubot for writing short notes where I want the citations processed.

But maybe you mean a more abstract API that'll just run citation JSON given an identifier.

[agitter]

I was thinking of a few lines of code that would show how the citation_to_citeproc function can be used. One of the test cases is close to what I had in mind:
https://github.com/greenelab/manubot/blob/f456155e6cbe83c32c80f74ad24bc069beb0bfc7/tests/test_citations.py#L76-L88

Provide an identifier and you can easily get authors, title, and other metadata.

[slochower]

Are you thinking it would be good if this could be called directly, e.g., manubot --get-citation="arxiv:cond-mat/0703470v2" returning either the JSON or CSL?

[agitter]

I hadn't thought about that, but maybe? I was thinking about importing and using that function directly as part of a larger Python codebase.

[dhimmel]

The citation identifier to citeproc is widely applicable beyond Manubot. Were we to advertise this functionality and make it easily usable, it could gain a lot of usage. To maximize usage, it would probably be best as a standalone library. However, in the meantime we could create some documentation for manubot.citations and manubot.metadata. In fact, manubot.metadata should probably become manubot.citation.retreve or something.

I will look into setup.py to see if there's an easy way to install only the dependencies required for citaiton processing.

I am guessing some users will want to pass full citations like doi:10.7554/eLife.32822, whereas others will just want to directly call get_pubmed_citeproc(29424689).

Larger picture, I think we should move the Manubot USAGE.md to this repository. Probably host documentation for Manubot in this repository rather than rootstock. We could even display the doc at a Manubot domain. I digress. Will open a new issue.

[dhimmel]

Good idea @slochower. I'd be in favor of a CLI like:

manubot cite "arxiv:cond-mat/0703470v2"

We may want to change the current manubot CLI command to manubot process or something.

BTW. Casey just acquired manubot.org. manu.bot would be better, but is administered by Amazon and only eligible for certain bots.

[agitter]

The new CLI in #42 is really great. Do we also want to show an example of access through a Python script?

>>> from manubot.cite import citation_to_citeproc
>>> csl_item = citation_to_citeproc('url:https://greenelab.github.io/meta-review/')
>>> csl_item['title']
'Open collaborative writing with Manubot'

[dhimmel]

Do we also want to show an example of access through a Python script?

Yes but not until the internal API stabilizes. I still am thinking about moving some functions and refactoring.

[agitter]

That makes sense.

[dhimmel]

BTW. Casey just acquired manubot.org. manu.bot would be better, but is administered by Amazon and only eligible for certain bots.

Somewhat related, it'd be great if we could get the @manubot GitHub handle to host our repositories. See manubot-zz/manuel.botero-hotmail.com#1