collectall: collect/embed into sphinx docs all references found in the project for inclusion in the docs etc

[yarikoptic]

This is worth which was done years back at one of the brainhacks but never finalized. The idea (also in #116) was to

• collect all references which could be found in the Python package
• export them as restructured text for sphinx so could be included in the package documentation

It should be possible to instruct on how export should be "presented", e.g. could group based on tags or package submodules. Moreover, could include references to code where those citations were found.

Also that export should provide references so the documentation system (sphinx) could then use them through out the documentation.

This way, it should be possible to centralize relevant references of implemented methods, reference documentations etc in the code, have them discoverable via duecredit for specific executions, but then also presented on the documentation website in a centralized consistent mannger.

Ideal implementation should be done in a modular fashion to support various export targets, e.g. markdown and mkdocs, in addition to restructured text and sphinx.

[mkhorton]

This would be a great feature! This is one of the main reasons we'd like to adopt duecredit; we develop a large library that cites many third-party packages/papers, and we want to have a systematic way of making sure we collect them all in a single page in our docs.

[yarikoptic]

Thanks for chiming in. We have never finalized this feature but specific demand/use cases might help to inspire finishing it. What is your exact use case? (sphinx or some other system? how presentation of those items would you like to see etc)

[mkhorton]

Sure, I can give a specific example. We’re using Sphinx but any method that collects all citations within one library would work, even just outputting to plain text.

We’re trialling duecredit in pymatgen and specifically we have this page which can easily get out of date, so that’s what I’m looking to automate.

My understanding of duecredit right now is that we’d actually have to have a single script that uses every function in our library to obtain this output, which isn’t really practical (unless we attach it to our test suite, but even then it might miss something).

Thank you for all your work/effort on this!

[yarikoptic]

Exactly! that is why this PR was born with idea to just walk the entire python package and collect those dcite'd methods... I wish we finished it up... Do you have a branch where you annotated your package with duecredit already?

[mkhorton]

We already have the annotations in the master branch (it gave us a reason to check our references, and we figured it would be useful for others regardless). I did recently notice that some annotations had been mistakenly applied to a class instead of a function/init however, so we’d need to fix that.