From 36c6f9d4168100412aa473fef6af5d2635ee5885 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 2 Mar 2020 23:01:49 -0800 Subject: [PATCH 1/2] fixing citations --- docs/citations.ipynb | 96 ----------------------------------- docs/features/citations.ipynb | 56 +++++++++----------- docs/toc.yml | 1 - 3 files changed, 25 insertions(+), 128 deletions(-) delete mode 100644 docs/citations.ipynb diff --git a/docs/citations.ipynb b/docs/citations.ipynb deleted file mode 100644 index 837910f65..000000000 --- a/docs/citations.ipynb +++ /dev/null @@ -1,96 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Including citations in your book\n", - "\n", - "✨**experimental**✨" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Because `jupyter-book` is built on top of Sphinx, we can use the excellent\n", - "[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)\n", - "extension to include citations and a bibliography with your book.\n", - "\n", - "## How to use citations\n", - "\n", - "Including citations with your markdown files or notebooks is done in the following\n", - "way.\n", - "\n", - "1. Modify the file in `_bibliography/references.bib`. This has a few sample citations\n", - "in bibtex form. Update as you wish!\n", - "2. In your content, add the following text to include a citation\n", - " \n", - " ```\n", - " {cite}`mybibtexcitation`\n", - " ```\n", - "\n", - " For example, this text\n", - " \n", - " ```\n", - " {cite}`holdgraf_rapid_2016`\n", - " ```\n", - " \n", - " generates this citation: {cite}`holdgraf_rapid_2016`\n", - " \n", - " You can also include multiple citations in one go, like so:\n", - " \n", - " ```\n", - " {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`\n", - " ```\n", - " \n", - " becomes {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`.\n", - " \n", - "3. Generate a bibliography on your page by using the following text:\n", - "\n", - " ````\n", - " ```{bibliography} path/to/your/bibtexfile.bib\n", - " ```\n", - " ````\n", - " \n", - " This will generate a bibliography for your entire bibtex file, like so:\n", - " \n", - " ```{bibliography} ../references.bib\n", - " ```\n", - "\n", - "When your book is built, the bibliography and citations will now be included." - ] - } - ], - "metadata": { - "jupytext": { - "formats": "ipynb,md" - }, - "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" - }, - "widgets": { - "application/vnd.jupyter.widget-state+json": { - "state": {}, - "version_major": 2, - "version_minor": 0 - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/features/citations.ipynb b/docs/features/citations.ipynb index d6297a373..70b997a87 100644 --- a/docs/features/citations.ipynb +++ b/docs/features/citations.ipynb @@ -6,21 +6,18 @@ "source": [ "# Including citations in your book\n", "\n", - "✨**experimental**✨" + "```{warn}\n", + "✨✨experimental✨✨\n", + "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Because `jupyter-book` is built on top of Jekyll, we can use the excellent\n", - "[jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) book to\n", - "include citations and a bibliography with your book.\n", - "\n", - "**Note that this only works if you're building your book HTML locally and\n", - "hosting the HTML files online somewhere**. This can still use GitHub pages, but\n", - "not the auto-generation of a cite from markdown files feature of GitHub pages.\n", - "This is because GitHub pages doesn't include the `jekyll-scholar` plugin.\n", + "Because `jupyter-book` is built on top of Sphinx, we can use the excellent\n", + "[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)\n", + "extension to include citations and a bibliography with your book.\n", "\n", "## How to use citations\n", "\n", @@ -32,42 +29,39 @@ "2. In your content, add the following text to include a citation\n", " \n", " ```\n", - " {% raw %}{% cite bibtex_shortname %}{% endraw %}\n", + " {cite}`mybibtexcitation`\n", + " ```\n", + "\n", + " For example, this text\n", + " \n", + " ```\n", + " {cite}`holdgraf_rapid_2016`\n", " ```\n", " \n", - " For example, this text: `{% raw %}{% cite holdgraf_evidence_2014 %}{% endraw %}` generates this citation: {% cite holdgraf_evidence_2014 %}\n", + " generates this citation: {cite}`holdgraf_rapid_2016`\n", " \n", " You can also include multiple citations in one go, like so:\n", " \n", - " `{% raw %}{% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}{% endraw %}` becomes {% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}\n", + " ```\n", + " {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`\n", + " ```\n", + " \n", + " becomes {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`.\n", " \n", "3. Generate a bibliography on your page by using the following text:\n", "\n", + " ````\n", + " ```{bibliography} path/to/your/bibtexfile.bib\n", " ```\n", - " {% raw %}{% bibliography %}{% endraw %}\n", - " ```\n", + " ````\n", " \n", - " This will generate a bibliography for your entire bibtex file. If you'd like to restrict the\n", - " bibliography to only the citations you've used on a page, use the following syntax:\n", + " This will generate a bibliography for your entire bibtex file, like so:\n", " \n", + " ```{bibliography} ../references.bib\n", " ```\n", - " {% raw %}{% bibliography --cited %}{% endraw %}\n", - " ```\n", - " \n", - "When your book is built, the bibliography and citations will now be included. For example,\n", - "see the Bibliography generated below!\n", - "\n", - "## References\n", "\n", - "{% bibliography --cited %}" + "When your book is built, the bibliography and citations will now be included." ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { diff --git a/docs/toc.yml b/docs/toc.yml index f33e14a93..f267f822e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,5 +1,4 @@ - path: index -- path: citations - path: guide/01_overview not_numbered: true expand_sections: true From b3739ffa5cdbcdcdab1b330398ef18882533a60e Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 2 Mar 2020 23:02:40 -0800 Subject: [PATCH 2/2] Update docs/features/citations.ipynb --- docs/features/citations.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/citations.ipynb b/docs/features/citations.ipynb index 70b997a87..de8f37f98 100644 --- a/docs/features/citations.ipynb +++ b/docs/features/citations.ipynb @@ -6,7 +6,7 @@ "source": [ "# Including citations in your book\n", "\n", - "```{warn}\n", + "```{warning}\n", "✨✨experimental✨✨\n", "```" ]