Add support for in-text citations

doc/a-normal-rst-file.rst

@@ -187,6 +187,7 @@ your ``conf.py`` and select the BibTeX file(s) you want to use:
     ]
 
     bibtex_bibfiles = ['my-references.bib']
+    bibtex_reference_style = 'author_year'
 
 Afterwards all the references defined in the bibliography file(s) can be used
 throughout the Jupyter notebooks and other source files as detailed in the following.
@@ -204,6 +205,14 @@ You can create citations like :cite:`perez2011python`:
 
     :cite:`perez2011python`
 
+You can also create so-called in-text citations,
+where the names of the authors, for example :cite:t:`perez2011python`,
+are part of the sentence:
+
+.. code-block:: rst
+
+    :cite:t:`perez2011python`
+
 You can create similar citations in Jupyter notebooks with a special HTML
 syntax, see the section about
 `citations in Markdown cells <markdown-cells.ipynb#Citations>`__.
@@ -229,6 +238,12 @@ citations like :footcite:`perez2011python`.
 
     :footcite:`perez2011python`
 
+In-text citations like :footcite:t:`kluyver2016jupyter` can be created like this:
+
+.. code-block:: rst
+
+    :footcite:t:`kluyver2016jupyter`
+
 Also footnote citations can be used within Jupyter notebooks with a special HTML syntax,
 see the section about
 `footnote citations in Markdown cells <markdown-cells.ipynb#Footnote-citations>`__.

doc/conf.py

@@ -88,7 +88,9 @@
     'tex': {'tags': 'ams', 'useLabelIds': True},
 }
 
+# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html
 bibtex_bibfiles = ['references.bib']
+bibtex_reference_style = 'author_year'
 
 # Support for notebook formats other than .ipynb
 nbsphinx_custom_formats = {

doc/markdown-cells.ipynb

@@ -199,10 +199,10 @@
     "`nbconvert` supports citations using a special HTML-based syntax.\n",
     "`nbsphinx` supports the same syntax.\n",
     "\n",
-    "Example: <cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>.\n",
+    "Example: <cite data-cite=\"kluyver2016jupyter\">(Kluyver et al. 2016)</cite>.\n",
     "\n",
     "```html\n",
-    "<cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>\n",
+    "<cite data-cite=\"kluyver2016jupyter\">(Kluyver et al. 2016)</cite>\n",
     "```\n",
     "\n",
     "You don't actually have to use `<cite>`,\n",
@@ -213,6 +213,14 @@
     "<strong data-cite=\"perez2011python\">Python: An Ecosystem for Scientific Computing</strong>\n",
     "```\n",
     "\n",
+    "In-text citations like\n",
+    "<cite data-cite-t=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>\n",
+    "can be created like this:\n",
+    "\n",
+    "```html\n",
+    "<cite data-cite-t=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>\n",
+    "```\n",
+    "\n",
     "You'll also have to define a list of references,\n",
     "see [the section about references](a-normal-rst-file.rst#references).\n",
     "\n",
@@ -224,12 +232,20 @@
     "\n",
     "Depending on whether the documentation is rendered into HTML or into LaTeX/PDF, the citations are either placed into a bibliography as ordinary citations (HTML output) or placed into the footnotes of the citation's respective page (PDF).\n",
     "\n",
-    "Example: <cite data-footcite=\"perez2011python\">Pérez et al. (2011)</cite>.\n",
+    "Example: <cite data-footcite=\"perez2011python\">(Pérez et al. 2011)</cite>.\n",
     "\n",
     "```html\n",
-    "<cite data-footcite=\"perez2011python\">Pérez et al. (2011)</cite>\n",
+    "<cite data-footcite=\"perez2011python\">(Pérez et al. 2011)</cite>\n",
     "```\n",
     "\n",
+    "Example for an in-text citation:\n",
+    "<cite data-footcite-t=\"perez2011python\">Pérez et al. (2011)</cite>.\n",
+    "\n",
+    "```html\n",
+    "<cite data-footcite-t=\"perez2011python\">Pérez et al. (2011)</cite>\n",
+    "```\n",
+    "\n",
+    "\n",
     "As footnote references are restricted to their own Jupyter notebook or other source file, a raw nbconvert cell of reST format (see [the section about raw cells](raw-cells.ipynb)) can be added to the notebook, containing the\n",
     "\n",
     "```rst\n",

src/nbsphinx/__init__.py

@@ -865,6 +865,17 @@ def convert_pandoc(text, from_format, to_format):
     return markdown2rst(text)
 
 
+_CITE_ROLES = {
+    'data-cite': 'cite',
+    'data-footcite': 'footcite',
+}
+_CITE_ROLES.update({
+    f'{k}-{suffix}': f'{v}:{suffix}'
+    for k, v in _CITE_ROLES.items()
+    for suffix in ('p', 'ps', 't', 'ts', 'ct', 'cts')
+})
+
+
 class CitationParser(html.parser.HTMLParser):
 
     def handle_starttag(self, tag, attrs):
@@ -879,12 +890,11 @@ def handle_startendtag(self, tag, attrs):
 
     def _check_cite(self, attrs):
         for name, value in attrs:
-            if name == 'data-cite':
-                self.cite = ':cite:`' + value + '`'
-                return True
-            elif name == 'data-footcite':
-                self.cite = ':footcite:`' + value + '`'
-                return True
+            try:
+                self.cite = f':{_CITE_ROLES[name]}:`{value}`'
+            except KeyError:
+                continue
+            return True
         return False
 
     def reset(self):