Docs docs: Add instructions for embedding files in docs

doc/source/users_guide/working-with-documentation/embed-example-markdown.md

@@ -0,0 +1,10 @@
+---
+orphan: true
+---
+
+Everything in this paragraph is just the contents of
+`doc/source/users_guide/working-with-documentation/embed-example-markdown.md`. It's in the same directory
+as the "Tips for working with Markdown" source file, so we only had to specify the
+filename. If it were in a different directory, we would specify the path relative to "Tips for
+working with Markdown". (Note that this file does NOT follow the "no line breaks within
+paragraphs" style convention; this is purely for readability of the embedded text.)

doc/source/users_guide/working-with-documentation/embed-example-python.py

@@ -0,0 +1,6 @@
+"""
+This is just an example Python file that will be literalinclude'ed
+"""
+
+print("Hello world")
+my_list = ["foo", "bar"]

doc/source/users_guide/working-with-documentation/embed-example-rst.rst

@@ -0,0 +1,7 @@
+Everything in this paragraph is just the contents of
+``doc/source/users_guide/working-with-documentation/embed-example-rst.rst``. It's in the same
+directory as the "Tips for working with reStructuredText" source file, so we only had to
+specify the filename. If it were in a different directory, we would specify the path
+relative to "Tips for working with reStructuredText". (Note that this file does NOT follow
+the "no line breaks within paragraphs" style convention; this is purely for readability of
+the embedded text.)

doc/source/users_guide/working-with-documentation/tips-for-working-with-markdown.md

@@ -104,3 +104,68 @@ Here's a hint. Synonyms you can put in the `{}` instead of `hint` include `impor
 ```{hint}
 Here's a hint. Synonyms you can put in the `{}` instead of `hint` include `important` and `tip`.
 ```
+
+## Markdown: Embedding a different Markdown file
+It can be useful to embed one Markdown file within another. This is done in this documentation documentation, for instance, to embed `doc/source/users_guide/working-with-documentation/embed-build-cmd.md` on three different pages.
+
+As an example, here's what an embedding looks like:
+~~~
+That becomes:
+```{include} embed-example-markdown.md
+```
+~~~
+
+That becomes:
+```{include} embed-example-markdown.md
+```
+
+See [the MyST Markdown documentation for the "include" directive](https://mystmd.org/guide/directives#directive-include) for more information.
+
+You can also embed literal contents of any file without the rendering:
+~~~
+That becomes the literal contents:
+```{literalinclude} embed-example-markdown.md
+```
+~~~
+
+That becomes the literal contents:
+```{literalinclude} embed-example-markdown.md
+```
+
+(The first three lines are to indicate to Sphinx that it's okay for that file to not be included in any Table of Contents; i.e., to suppress the `WARNING: document isn't included in any toctree [toc.not_included]` build message.)
+
+You can also get fancy:
+~~~
+```{literalinclude} embed-example-python.py
+:language: python
+:linenos:
+```
+~~~
+
+Becomes (note syntax highlighting):
+
+```{literalinclude} embed-example-python.py
+:language: python
+:linenos:
+```
+
+And
+~~~
+```{literalinclude} embed-example-python.py
+:language: python
+:linenos:
+:start-at: print
+:lineno-match:
+```
+~~~
+
+Becomes:
+
+```{literalinclude} embed-example-python.py
+:language: python
+:linenos:
+:start-at: print
+:lineno-match:
+```
+
+See [the MyST Markdown documentation for the `include` directive](https://mystmd.org/guide/directives#directive-include) for more information (all options apply to `literalinclude` as well).

doc/source/users_guide/working-with-documentation/tips-for-working-with-rst.rst

@@ -150,6 +150,50 @@ There are also a number of built-in admonition types that get their own special
 
 
 
+reStructuredText: Embedding a different reStructuredText file
+-------------------------------------------------------------
+
+.. code-block:: reStructuredText
+
+  .. include:: embed-example-rst.rst
+
+Becomes:
+
+.. include:: embed-example-rst.rst
+
+You can also embed literal contents of any file without the rendering:
+
+.. code-block:: reStructuredText
+
+  .. literalinclude:: embed-example-rst.rst
+     :language: restructuredtext
+
+That becomes the literal contents (note syntax highlighting):
+
+.. literalinclude:: embed-example-rst.rst
+   :language: restructuredtext
+
+You can also get fancy:
+
+.. code-block:: reStructuredText
+
+  .. literalinclude:: embed-example-python.py
+     :language: python
+     :start-at: print
+     :linenos:
+     :lineno-match:
+
+Becomes:
+
+.. literalinclude:: embed-example-python.py
+   :language: python
+   :start-at: print
+   :linenos:
+   :lineno-match:
+
+See `the Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude>`_ for more options to the ``literalinclude`` directive.
+
+
 reStructuredText: Text superscripts and subscripts
 --------------------------------------------------------------
 
@@ -172,4 +216,4 @@ Note that these instructions apply to text (i.e., not in inline or block math).
 reStructuredText: Common error messages and how to handle them
 --------------------------------------------------------------
 
-See :ref:`common-rst-errors`.
+See :ref:`common-rst-errors`.