Add bibliography example (#17)

* Add bibliography example

* Remove references (obsolete)

README.md

@@ -17,6 +17,9 @@ Inspired by [literate programming](http://literateprogramming.com) and [Cookiecu
 
     > Documentation is often never priotized until last minute. The <span style="color:#3EACAD">template</span> aims to revert the malpractice by setting up the documentation as an integral part of the code repository. With the power of [Jupyter Book](https://jupyterbook.org), data practioners have a way to share [Jupyter notebooks](https://jupyter.org) on [GitHub Pages](https://pages.github.com) in a standardized and effortless way.
 
+- **docs/bibliography.bib**
+    > A `bibliography` using the [BibTeX](https://www.bibtex.org/Format/) format.
+
 - **data/**
     > Placeholder folder for data. Data is immutable. By default, the data folder is present but ignored from version control, in order to prevent files of being mistakenly versioned in the code repository.
 

docs/_config.yml

@@ -27,6 +27,11 @@ html:
 execute:
   execute_notebooks: "off"
 
+#######################################################################################
+# Bibliography settings
+bibtex_bibfiles:
+    - docs/bibliography.bib
+
 #######################################################################################
 # Sphinx settings
 sphinx:

docs/_toc.yml

@@ -8,6 +8,7 @@ parts:
       - file: notebooks/world-bank-api.ipynb
       - file: notebooks/world-bank-package.ipynb
       - file: notebooks/nasa-apod.ipynb
+      - file: notebooks/bibliography.ipynb
   - caption: Additional Resources
     chapters:
       - url: https://datapartnership.org

docs/bibliography.bib

@@ -0,0 +1,39 @@
+@book{WorldBank2021WorldDevelopmentReport,
+  author      = {{World Bank}},
+  publisher = {World Bank},
+  url         = {http://hdl.handle.net/10986/35218},
+  date        = {2021},
+  note        = {License: CC BY 3.0 IGO},
+  title       = {{W}orld {D}evelopment {R}eport 2021 : {D}ata for {B}etter {L}ives},
+  type        = {World Development Report},
+  year         = {2021},
+}
+@book{WorldBank2022WorldDevelopmentReport,
+  author      = {{World Bank}},
+  publisher = {World Bank},
+  url         = {http://hdl.handle.net/10986/36883},
+  date        = {2022},
+  note        = {License: CC BY 3.0 IGO},
+  title       = {{W}orld {D}evelopment {R}eport 2022 : {F}inance for an {E}quitable {R}ecovery},
+  type        = {World Development Report},
+  year         = {2022},
+},
+@book{WorldBank2023WorldDevelopmentReport,
+  author      = {{World Bank}},
+  publisher = {World Bank},
+  url         = {https://openknowledge.worldbank.org/handle/10986/39696},
+  date        = {2023},
+  note        = {License: CC BY 3.0 IGO},
+  title       = {{W}orld {D}evelopment {R}eport 2021 : {M}igrants, {R}efugees, and {S}ocieties},
+  type        = {World Development Report},
+  year         = {2023},
+}
+@misc{sdgatlas2020,
+  author      = {Pirlea, A. F. and U. Serajuddin and D. Wadhwa and M. Welch and A. Whitby},
+  publisher = {World Bank},
+  url         = {https://datatopics.worldbank.org/sdgatlas.},
+  date        = {2020},
+  note        = {License: CC BY 3.0 IGO},
+  title       = {{A}tlas of the {S}ustainable {D}evelopment {G}oals 2020: {F}rom {W}orld {D}evelopment {I}ndicators},
+  year         = {2020},
+}

notebooks/bibliography.ipynb

@@ -0,0 +1,173 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "90700fdc-fcc7-4e54-8c9e-449879d8c66d",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "(bibliography)=\n",
+    "\n",
+    "# Including Bibliography"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "14e89727",
+   "metadata": {},
+   "source": [
+    "Including a bibliography is of utmost importance in any academic or research work. A bibliography serves as a comprehensive list of all the sources consulted and referenced during the creation of a paper, essay, or any scholarly project. It not only adds credibility to the work but also demonstrates the depth of research conducted by the author. By providing a bibliography, the author acknowledges the contributions of other scholars and researchers, thereby showing respect for intellectual property and avoiding plagiarism. \n",
+    "\n",
+    "Furthermore, a bibliography allows readers to delve deeper into the subject matter, explore related sources, and verify the accuracy and reliability of the information presented. In essence, the inclusion of a well-constructed bibliography is an essential aspect of scholarly writing that promotes transparency, authenticity, and the advancement of knowledge."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "b4c0f3e8-7756-41bb-aa21-cc2eee5ff67f",
+   "metadata": {},
+   "source": [
+    "## Usage\n",
+    "\n",
+    "```{seealso}\n",
+    "[Jupyter Book: Citations and bibliographies](https://jupyterbook.org/en/stable/content/citations.html)\n",
+    "```\n",
+    "\n",
+    "The <span style=\"color:#3EACAD\">template</span> includes [`docs/bibliography.bib`](docs/bibliography.bib) as example, containing an entry to the World Bank flagship publication [World Development Report 2021](https://www.worldbank.org/en/publication/wdr2021) in [BibTeX Format](http://www.bibtex.org/Format). \n",
+    "\n",
+    "To include a **citation**, we use the syntax as shown below.\n",
+    " \n",
+    "````md\n",
+    "{cite}`WorldBank2021WorldDevelopmentReport`\n",
+    "````\n",
+    "\n",
+    "Additionally, we can use different citation styles.\n",
+    "\n",
+    "- **{cite:t}**: {cite:t}`WorldBank2021WorldDevelopmentReport`\n",
+    "\n",
+    "- **{cite:p}**: {cite:p}`WorldBank2021WorldDevelopmentReport`\n",
+    "\n",
+    "\n",
+    "```{seealso}\n",
+    "For a more complete list of in-line citation styles, check out the [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#roles-and-directives).\n",
+    "```\n",
+    "\n",
+    "To include the **bibliography**, we use the syntax as shown below. Note that this will include all citations throughout the book. \n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    "```\n",
+    "\n",
+    "To include only the **local bibliography**, we use hte syntax as shown below. \n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    ":filter: docname in docnames\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    ":filter: docname in docnames\n",
+    "```\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d0066241",
+   "metadata": {},
+   "source": [
+    "## Bibliography Styles\n",
+    "\n",
+    "\n",
+    "### `alpha`\n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    ":style: alpha\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    ":style: alpha\n",
+    "```\n",
+    "\n",
+    "### `plain`\n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    ":style: plain\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    ":style: plain\n",
+    "```\n",
+    "\n",
+    "### `unsrt`\n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    ":style: unsrt\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    ":style: unsrt\n",
+    "```\n",
+    "\n",
+    "### `unsrtalpha`\n",
+    "\n",
+    "````md\n",
+    "```{bibliography}\n",
+    ":style: unsrtalpha\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "```{bibliography}\n",
+    ":style: unsrtalpha\n",
+    "```\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "b0e84fdb",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.9.12"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "b6702b69e93007336b96338c5a331192f07cedff01d36d4dcfa0f842adb718ad"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}