DOC: Show how to use Markdown source files

doc/README.md → doc/README

@@ -1,5 +1,5 @@
 This folder contains the source files for the documentation.
-See [CONTRIBUTING](../CONTRIBUTING.rst) for how to create the HTML and LaTeX
+See ../CONTRIBUTING.rst for how to create the HTML and LaTeX
 files from these sources.
 
 The online documentation is available at https://nbsphinx.readthedocs.io/.

doc/a-markdown-file.md

@@ -0,0 +1,43 @@
+# Using Markdown Files
+
+Sphinx on its own doesn't know how to handle Markdown files,
+but there are extensions that enable their usage as Sphinx source files.
+For an example, see the
+[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html).
+
+Alternatively, when using `nbsphinx` it is also possible to use Markdown
+files via [custom notebook formats](custom-formats.ipynb).
+
+You only need to install the [jupytext](https://jupytext.readthedocs.io/)
+package and add a configuration setting to `conf.py`,
+which can be used to select one of
+[several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats.html#markdown-formats)
+(here we are using R Markdown):
+
+```python
+nbsphinx_custom_formats = {
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
+}
+```
+
+This very page was generated from a Markdown file using these settings.
+
+
+## Links to Notebooks (and Other Sphinx Source Files)
+
+Links to other Sphinx source files can be created like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks).
+
+
+## Math
+
+Math equation can be used just like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Equations).
+
+Inline like this: $\text{e}^{i\pi} = -1$.
+
+Or as a separate block:
+
+\begin{equation*}
+\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)
+\end{equation*}

doc/conf.py

@@ -80,6 +80,7 @@
 # Support for notebook formats other than .ipynb
 nbsphinx_custom_formats = {
     '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}],
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
 }
 
 # -- The settings below this line are not specific to nbsphinx ------------

doc/custom-formats.pct.py

@@ -68,7 +68,8 @@
 # .. literalinclude:: conf.py
 #     :language: python
 #     :start-at: nbsphinx_custom_formats
-#     :lines: -3
+#     :lines: -4
+#     :emphasize-lines: 2
 
 # %% [markdown]
 # Another example is [this gallery example page](gallery/due-rst.pct.py).

doc/index.rst

@@ -20,6 +20,7 @@ was generated from Jupyter notebooks.
     subdir/*
     custom-css
     a-normal-rst-file
+    a-markdown-file
     links
     contributing
     version-history