Create a list with all the papers that cite yours
Project description
sphinxcontrib-citations
It is often the case that open-source software enables new scientific
developments. When this happens, it is desirable to highlight which new results
were obtained with a given piece of software. If your project has one or more
associated published resources (for example, in the Journal of Open-Source
Software, or in Zenodo), you can use sphinxcontrib-citations
to generate a
page in your documentations that lists the papers that cite your code.
sphinxcontrib-citations
is an Sphinx extension that uses NASA's ADS to look up
which papers cite a given list of references. sphinxcontrib-citations
is
currently in a state of minimum-viable-product: the basic features are
available, but not much else. Pull request are welcome.
To use sphinxcontrib-citations
, first install it and add it to the
extensions
variable in your conf.py
as sphinxcontrib.citations
.
sphinxcontrib-citations
has only three options:
citations_ads_token
: this is the ADS API token, and it required for the correct functioning of the extension. You need a freely obtainable API token to use this package. Read more about NASA ADS API.citations_bibcode_list
: this is the list of bibcodes for which citations have to be found. You can find the bibcode for a given paper on ADS.citations_bibtex_file
: this is the name of the.bib
file that will be generated. If not specified, it will besphinxcontrib_citations.bib
. If a file with the given path already exists, it will be silently overwritten.
When you compile your documentation, sphinxcontrib-citations
will find all the
references and create a bib
file. Then, sphinxcontrib-citations
interfaces
with sphinxcontrib-bibtex
to produce the page. You can use all the options
provided by that package. A simple page might look like:
Papers citing this software
=============================================
.. bibliography:: sphinxcontrib_citations.bib
:list: enumerated
:all:
Make sure that the name of the file matches your choice for
citations_bibtex_file
.
ADS API Token in GitHub actions
Clearly, committing the API token directly to GitHub is not a good idea. GitHub actions support encrypted secrets that can be used to safely store the token.
Assuming you create a repository secret named ADS_API
(that contains the
token), you can pass it to Sphinx
through an environment variable. For
instance, the action step might look like:
- name: Produce documentation
env:
ADS_API: ${{ secrets.ADS_API }}
run: |
make html
with citations_ads_token = os.environ["ADS_API"]
in the conf.py
.
Example
For an example, see kuibit.
The relevant Sphinx configuration settings that generated this example are:
citations_ads_token = os.environ["ADS_API"]
citations_bibcode_list = ["2021JOSS....6.3099B"]
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxcontrib_citations-0.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe95b7c2ce859783a25eb9cf8be893b7a54eedd2ea4d1b477ac3227bc8b94fad |
|
MD5 | 1461aeb35313ffbc5d5057be8f328940 |
|
BLAKE2b-256 | 4f875c82a600a1da5fef26b5d98aef912fe45ebedf1c7b3b494570d68513015c |
Hashes for sphinxcontrib_citations-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | beb96c8c93fdafd07bf748d34ec98ba99210f5dce3e7af86eb4a7a1ce913d6e7 |
|
MD5 | 4f788abe5ad10ee9ecc5f91b4e4aeb9e |
|
BLAKE2b-256 | 01937fc2057a5dd1b0e84d799969f57524a150d97cb0337ab631c8ac7c2c3c2f |