sphinx-astrorefs¶
Astro-style references in Sphinx documents
About¶
sphinx-astrorefs is a Sphinx extension for formatting citations and references in a style similar to that used in the astrophysics literature. It is built on top of sphinxcontrib-bibtex, a Sphinx extension for including bibtex citations in Sphinx documents. By pre- and post-processing the input and output from Sphinx and sphinxcontrib-bibtex, sphinx-astrorefs allows you to obtain
citations in the astro-specific style in the HTML and LaTeX rendering of your Sphinx documents.
Installation¶
Installation is easiest using pip
pip install sphinx-astrorefs
That’s it!
Usage¶
To start using this extension, add it to your extensions in your project’s conf.py, e.g.,
extensions= ['sphinxcontrib.bibtex','sphinx_astrorefs']
(note the underscore instead of a dash) where we include sphinxcontrib.bibtex, because this extensions assumes that you are using this extension for bibliography management.
Then place the bibliography somewhere in your Sphinx document tree, using :style: astrostyle, e.g.,
.. bibliography::
:cited:
:style: astrostyle
If you are using sphinxcontrib.bibtex version < 2, you would also specify the .bib file in the first line as, e.g., .. bibliography:: references.bib and you could indicate the bibtex’s file encoding as another line, e.g., :encoding: latin. In sphinxcontrib.bibtex version >= 2, you instead specify the .bib file using the bibtex_bibfiles configuration parameter in your conf.py (e.g., bibtex_bibfiles= ['references.bib']) and the encoding is another configuration parameter (e.g., bibtex_encoding= 'latin').
Then you can use the same citation commands as you normally would in sphinxcontrib.bibtex, e.g.,
Dark matter was first proposed by :cite:`Zwicky1933` to explain
the high velocity dispersion of galaxies in the Coma cluster
is rendered as
Dark matter was first proposed by Zwicky (1933) to explain the high velocity dispersion of galaxies in the Coma cluster.
A regular invocation of :cite: like this is rendered as AUTHOR (YEAR) (that is, as \citet in LaTeX’s natbib package). However, if you enclose the :cite: command in parentheses, the citation is rendered as (AUTHOR YEAR) (that is, the equivalent of natbib’s \citep). For example,
Further evidence for the existence of dark matter was provided by the
flat rotation curve of the Andromeda galaxy (:cite:`RubinFord1970`).
is rendered as
Further evidence for the existence of dark matter was provided by the flat rotation curve of the Andromeda galaxy (Rubin & Ford 1970).
Placing a colon : in front of the :cite: command causes the citation to simply appear as AUTHOR YEAR (the equivalent of natbib’s \citealt), e.g.,
Simulations of structure formation in a Universe dominated by weakly-interacting,
cold dark matter revealed that these simulations' large-scale structure is
consistent with observations (e.g., ::cite:`DavisEfstathiouFrenkWhite1985`).
is rendered as
Simulations of structure formation in a Universe dominated by weakly-interacting, cold dark matter revealed that these simulations’ large-scale structure is consistent with observations (e.g., Davis et al. 1985).
If you are writing in a Jupyter notebook included into your Sphinx document using, e.g., nbsphinx, the same rules apply, but the citation command in Markdown cells is <cite data-cite="LABEL">Somebody et al. (some year)</cite>, for example
Further simulations of the formation of individual galaxies in the cold-dark-matter
paradigm showed that the density profile of galaxies' dark-matter distributions
("halos") follows a universal
form (<cite data-cite="NavarroFrenkWhite1997">Navarro et al. 1997</cite>).
is rendered as
Further simulations of the formation of individual galaxies in the cold-dark-matter paradigm showed that the density profile of galaxies’ dark-matter distributions (“halos”) follows a universal form (Navarro et al. 1997).
Note here that what you put between the <cite> and </cite> tags does not get transferred to the output, the only part of this entire command that is used is the data-cite key, which is the bibtex key of the reference. Note further that you can use any HTML tag, as long as it has the data-cite attribute. Enclosing the <cite>...</cite> command in parentheses again produces an (AUTHOR YEAR) citation, while preceding the <cite> tag with a colon : produces AUTHOR YEAR.
sphinx-astrorefs follows the Astrophysical Journal’s rules for the number of authors to be displayed in the reference list. If you have been looking at the Reference section below, you will have noticed that all authors of the papers referenced so far are included, as up to five authors are shown in the author list. For larger collaborations, the first five authors are shown, e.g.,
An important clue as to the identity of dark matter was provided by
the failure of microlensing searches to find enough microlensing events
by compact halo objects towards the Large Magellanic Cloud to account
for all of the Milky Way's dark matter (e.g., ::cite:`AlcockEtAl2000`).
Thus, dark matter is not comprised of faint or dead stars.
is rendered as
An important clue as to the identity of dark matter was provided by the failure of microlensing searches to find enough microlensing events by compact halo objects towards the Large Magellanic Cloud to account for all of the Milky Way’s dark matter (e.g., Alcock et al. 2000). Thus, dark matter is not comprised of faint or dead stars.
and clicking on the reference, you see that the author list is cut at five authors followed by et al.. sphinx-astrorefs will also correctly render collaborations as part of the author list, e.g.,
Currently, the best measurements of the cosmic abundance of dark matter
are provided by observations of the anisotropies in the cosmic
microwave background, which show that dark matter is about five times
more abundance than ordinary baryonic matter (:cite:`Planck2016`).
is rendered as
Currently, the best measurements of the cosmic abundance of dark matter are provided by observations of the anisotropies in the cosmic microwave background, which show that dark matter is about five times more abundance than ordinary baryonic matter (Planck Collaboration et al. 2016).
Again, click on the reference to see how it is rendered in the bibliography.
sphinx-astrorefs will also correctly add a suffix ‘a’, ‘b’, etc. to the year if the labels of two bibliographical entries would otherwise be identical. For example,
In the last fifteen years, increasingly-large simulations of the formation
of individual galaxy halos have revealed the detailed small-scale properties
of dark-matter halos (e.g., ::cite:`SpringelEtAl2008a`), which in the
standard cold-dark-matter paradigm should have a large amount of substructure
down to Earth-mass scales. If dark-matter were to annihilate to photons, this
dense substructure would show up as extended gamma-ray sources in
the Milky Way's halo (:cite:`SpringelEtAl2008b`).
is rendered as
In the last fifteen years, increasingly-large simulations of the formation of individual galaxy halos have revealed the detailed small-scale properties of dark-matter halos (e.g., Springel et al. 2008a), which in the standard cold-dark-matter paradigm should have a large amount of substructure down to Earth-mass scales. If dark-matter were to annihilate to photons, this dense substructure would show up as extended gamma-ray sources in the Milky Way’s halo (Springel et al. 2008b).
The bibliography¶
Currently, the bibliography style implemented deviates from that used in astronomical journals in that it includes the title. Please open an issue if you would like the option of excluding the title.
If they are included in the bibtex entry, sphinx-astrorefs will use the doi, adsurl, or eprint fields to create links to:
the DOI (typically the journal version) using the
doifield (linked from the journal in the bibliography),the SAO/NASA Astrophysics Data System (ADS) entry using the
adsurlfield (linked from the volume), andthe arXiv.org entry using the
eprintfield (linked from the pages). Note that you can change thearxiv.orgpart of the arXiv URL using the configuration parameterastrorefs_arxiv_url, which isarxiv.orgby default (this allows you, for example, to use an arXiv mirror or to use theexport.arxiv.orgservice).
It is easiest to create your bibtex file by directly copying the ADS’ bibtex citation. However, those entries contain macros defined by the AAS journals for different journals (e.g., \apj for the Astrophysical Journal), which are typically resolved by the LaTeX document classes of journals or by including a LaTeX style file. To resolve these macros in sphinx-astrorefs, use the configuration value astrorefs_resolve_aas_macros= True in your Sphinx conf.py file. When you do
this, you need to also provide an input and an output .bib filename for the bibtex file, where the input file is the one you create from ADS and the output one is the one used by Sphinx (and so is the one you would reference in the bibtex_bibfiles configuration parameter [sphinxcontrib.bibtex version >= 2] or in the .. bibliography:: references.bib directive [sphinxcontrib.bibtex version < 2]). For example,
astrorefs_resolve_aas_macros= True
astrorefs_resolve_aas_macros_infile= 'refs.bib'
astrorefs_resolve_aas_macros_outfile= 'references.bib'
can be used when the bibtex file you create is refs.bib and you use the bibtex_files= ['references.bib'] configuration parameter (.. bibliography:: references.bib in sphinxcontrib.bibtex version < 2). Note that there is no support for processing multiple bibtex files like this at this point.
The pybtex astrostyle¶
Under the hood, sphinx-astrorefs uses pybtex to define the :style: astrostyle style used in the bibliography directive. This style consists of the AUTHOR YEAR labels, the rendering of the references in the bibliography, and the sorting of the references.
If you want to use this pybtex style in a different setting (that is, outside of Sphinx), you can simply do
from sphinx_astrorefs import pybtex_astro
pybtex_astro.register()
and then you can use the astrostyle as a pybtex style.
References¶
Alcock C., Allsman R., Alves D., Axelrod T., Becker A., et al. The MACHO Project: Microlensing Results from 5.7 Years of Large Magellanic Cloud Observations. Astrophys. J. 542, 281–307 (2000).
Davis M., Efstathiou G., Frenk C., & White S. The evolution of large-scale structure in a universe dominated by cold dark matter. Astrophys. J. 292, 371–394 (1985).
Navarro J., Frenk C., & White S. A Universal Density Profile from Hierarchical Clustering. Astrophys. J. 490, 493–508 (1997).
Planck Collaboration, Ade P., Aghanim N., Arnaud M., Ashdown M., et al. Planck 2015 results. XIII. Cosmological parameters. Astron. & Astrophys. 594, A13 (2016).
Rubin V. & Ford J. Rotation of the Andromeda Nebula from a Spectroscopic Survey of Emission Regions. Astrophys. J. 159, 379 (1970).
Springel V., Wang J., Vogelsberger M., Ludlow A., Jenkins A., et al. The Aquarius Project: the subhaloes of galactic haloes. Mon. Not. Roy. Astron. Soc. 391, 1685–1711 (2008a).
Springel V., White S., Frenk C., Navarro J., Jenkins A., et al. Prospects for detecting supersymmetric dark matter in the Galactic halo. Nature 456, 73–76 (2008b).
Zwicky F. Die Rotverschiebung von extragalaktischen Nebeln. Helvetica Physica Acta 6, 110–127 (1933).