docs/source/index.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# sphinx-astrorefs\n",
    "\n",
    "Astro-style references in Sphinx documents"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. contents:: Table of Contents\n",
    "   :local:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About\n",
    "\n",
    "``sphinx-astrorefs`` is a [Sphinx](https://www.sphinx-doc.org/en/master/) 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](https://sphinxcontrib-bibtex.readthedocs.io), 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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "Installation is easiest using ``pip``\n",
    "\n",
    "```\n",
    "pip install sphinx-astrorefs\n",
    "```\n",
    "\n",
    "That's it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage\n",
    "\n",
    "To start using this extension, add it to your ``extensions`` in your project's ``conf.py``, e.g.,\n",
    "```\n",
    "extensions= ['sphinxcontrib.bibtex','sphinx_astrorefs']\n",
    "```\n",
    "(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. "
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Then place the bibliography somewhere in your Sphinx document tree, using ``:style: astrostyle``, e.g.,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    .. bibliography::\n",
    "       :cited:\n",
    "       :style: astrostyle\n",
    "       \n",
    "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'``).\n",
    "\n",
    "Then you can use the same citation commands as you normally would in ``sphinxcontrib.bibtex``, e.g.,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    Dark matter was first proposed by :cite:`Zwicky1933` to explain \n",
    "    the high velocity dispersion of galaxies in the Coma cluster\n",
    "\n",
    "is rendered as \n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    Dark matter was first proposed by :cite:`Zwicky1933` to explain the high velocity dispersion of galaxies in the Coma cluster.\n",
    "    \n",
    "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,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    Further evidence for the existence of dark matter was provided by the \n",
    "    flat rotation curve of the Andromeda galaxy (:cite:`RubinFord1970`).\n",
    "\n",
    "is rendered as \n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    Further evidence for the existence of dark matter was provided by the flat rotation curve of the Andromeda galaxy (:cite:`RubinFord1970`).\n",
    "        \n",
    "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.,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    Simulations of structure formation in a Universe dominated by weakly-interacting,\n",
    "    cold dark matter revealed that these simulations' large-scale structure is\n",
    "    consistent with observations (e.g., ::cite:`DavisEfstathiouFrenkWhite1985`).\n",
    "\n",
    "is rendered as \n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    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`).\n",
    "    \n",
    "If you are writing in a Jupyter notebook included into your Sphinx document using, e.g., `nbsphinx <https://github.com/spatialaudio/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\n",
    "\n",
    ".. code-block:: html\n",
    "\n",
    "    Further simulations of the formation of individual galaxies in the cold-dark-matter\n",
    "    paradigm showed that the density profile of galaxies' dark-matter distributions \n",
    "    (\"halos\") follows a universal \n",
    "    form (<cite data-cite=\"NavarroFrenkWhite1997\">Navarro et al. 1997</cite>).\n",
    "    \n",
    "is rendered as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> 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>)."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "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``."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``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](#References) 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.,"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. code-block:: rst\n",
    "\n",
    "    An important clue as to the identity of dark matter was provided by\n",
    "    the failure of microlensing searches to find enough microlensing events\n",
    "    by compact halo objects towards the Large Magellanic Cloud to account\n",
    "    for all of the Milky Way's dark matter (e.g., ::cite:`AlcockEtAl2000`).\n",
    "    Thus, dark matter is not comprised of faint or dead stars.\n",
    "\n",
    "is rendered as \n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    An important clue as to the identity of dark matter was provided by\n",
    "    the failure of microlensing searches to find enough microlensing events\n",
    "    by compact halo objects towards the Large Magellanic Cloud to account\n",
    "    for all of the Milky Way's dark matter (e.g., ::cite:`AlcockEtAl2000`).\n",
    "    Thus, dark matter is not comprised of faint or dead stars.\n",
    "    \n",
    "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.,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    Currently, the best measurements of the cosmic abundance of dark matter\n",
    "    are provided by observations of the anisotropies in the cosmic \n",
    "    microwave background, which show that dark matter is about five times\n",
    "    more abundance than ordinary baryonic matter (:cite:`Planck2016`).\n",
    "\n",
    "is rendered as \n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    Currently, the best measurements of the cosmic abundance of dark matter\n",
    "    are provided by observations of the anisotropies in the cosmic \n",
    "    microwave background, which show that dark matter is about five times\n",
    "    more abundance than ordinary baryonic matter (:cite:`Planck2016`).\n",
    "    \n",
    "Again, click on the reference to see how it is rendered in the bibliography.\n",
    "\n",
    "``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,\n",
    "\n",
    ".. code-block:: rst\n",
    "\n",
    "    In the last fifteen years, increasingly-large simulations of the formation\n",
    "    of individual galaxy halos have revealed the detailed small-scale properties\n",
    "    of dark-matter halos (e.g., ::cite:`SpringelEtAl2008a`), which in the \n",
    "    standard cold-dark-matter paradigm should have a large amount of substructure\n",
    "    down to Earth-mass scales. If dark-matter were to annihilate to photons, this\n",
    "    dense substructure would show up as extended gamma-ray sources in\n",
    "    the Milky Way's halo (:cite:`SpringelEtAl2008b`).\n",
    "    \n",
    "is rendered as\n",
    "\n",
    ".. epigraph::\n",
    "\n",
    "    In the last fifteen years, increasingly-large simulations of the formation\n",
    "    of individual galaxy halos have revealed the detailed small-scale properties\n",
    "    of dark-matter halos (e.g., ::cite:`SpringelEtAl2008a`), which in the \n",
    "    standard cold-dark-matter paradigm should have a large amount of substructure\n",
    "    down to Earth-mass scales. If dark-matter were to annihilate to photons, this\n",
    "    dense substructure would show up as extended gamma-ray sources in\n",
    "    the Milky Way's halo (:cite:`SpringelEtAl2008b`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The bibliography\n",
    "\n",
    "Currently, the bibliography style implemented deviates from that used in astronomical journals in that it includes the title. Please open an [issue](https://github.com/jobovy/sphinx-astrorefs/issues) if you would like the option of excluding the title.\n",
    "\n",
    "If they are included in the ``bibtex`` entry, ``sphinx-astrorefs`` will use the ``doi``, ``adsurl``, or ``eprint`` fields to create links to:\n",
    "\n",
    "* the DOI (typically the journal version) using the ``doi`` field (linked from the journal in the bibliography), \n",
    "* the [SAO/NASA Astrophysics Data System](https://ui.adsabs.harvard.edu/about/) (ADS) entry using the ``adsurl`` field (linked from the volume), and \n",
    "* the [arXiv.org](https://arxiv.org/) entry using the ``eprint`` field (linked from the pages).\n",
    "    \n",
    "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,\n",
    "```\n",
    "astrorefs_resolve_aas_macros= True\n",
    "astrorefs_resolve_aas_macros_infile= 'refs.bib'\n",
    "astrorefs_resolve_aas_macros_outfile= 'references.bib'\n",
    "```\n",
    "    \n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The ``pybtex`` ``astrostyle``\n",
    "\n",
    "Under the hood, ``sphinx-astrorefs`` uses [pybtex](https://pybtex.org/) 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.\n",
    "\n",
    "If you want to use this ``pybtex`` style in a different setting (that is, outside of Sphinx), you can simply do\n",
    "```\n",
    "from sphinx_astrorefs import pybtex_astro\n",
    "pybtex_astro.register()\n",
    "```\n",
    "    \n",
    "and then you can use the ``astrostyle`` as a ``pybtex`` style."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. bibliography::\n",
    "   :cited:\n",
    "   :style: astrostyle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}