Format `literalinclude` directive options (#12780)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

doc/usage/restructuredtext/directives.rst

@@ -786,12 +786,12 @@ __ https://pygments.org/docs/lexers
       .. versionchanged:: 1.6.6
          LaTeX supports the ``emphasize-lines`` option.
 
-   .. rst:directive:option: force
+   .. rst:directive:option:: force
       :type: no value
 
-      Ignore minor errors on highlighting
+      Ignore minor errors on highlighting.
 
-      .. versionchanged:: 2.1
+      .. versionadded:: 2.1
 
    .. rst:directive:option:: caption: caption of code block
       :type: text
@@ -852,19 +852,14 @@ __ https://pygments.org/docs/lexers
       .. versionchanged:: 3.5
          Support automatic dedent.
 
-   .. rst:directive:option:: force
-      :type: no value
-
-      If given, minor errors on highlighting are ignored.
-
-      .. versionadded:: 2.1
-
 .. rst:directive:: .. literalinclude:: filename
 
    Longer displays of verbatim text may be included by storing the example text
    in an external file containing only plain text.  The file may be included
-   using the ``literalinclude`` directive. [#]_ For example, to include the
+   using the ``literalinclude`` directive. [#]_
-   Python source file :file:`example.py`, use::
+   For example, to include the Python source file :file:`example.py`, use:
+
+   .. code-block:: rst
 
       .. literalinclude:: example.py
 
@@ -872,150 +867,240 @@ __ https://pygments.org/docs/lexers
    it is absolute (starting with ``/``), it is relative to the top source
    directory.
 
-   **Additional options**
+   .. rubric:: General options
 
-   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
+   .. rst:directive:option:: class: class names
-   option to switch on line numbers, the ``lineno-start`` option to select the
+      :type: a list of class names, separated by spaces
-   first line number, the ``emphasize-lines`` option to emphasize particular
-   lines, the ``name`` option to provide an implicit target name, the
-   ``dedent`` option to strip indentation characters for the code block, and a
-   ``language`` option to select a language different from the current file's
-   standard language. In addition, it supports the ``caption`` option; however,
-   this can be provided with no argument to use the filename as the caption.
-   Example with options::
 
-      .. literalinclude:: example.rb
+      Assign `class attributes`_.
-         :language: ruby
+      This is a :dudir:`common option <common-options>`.
-         :emphasize-lines: 12,15-18
-         :linenos:
 
-   Tabs in the input are expanded if you give a ``tab-width`` option with the
+      .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
-   desired tab width.
 
-   Include files are assumed to be encoded in the :confval:`source_encoding`.
+      .. versionadded:: 1.4
-   If the file has a different encoding, you can specify it with the
-   ``encoding`` option::
 
-      .. literalinclude:: example.py
+   .. rst:directive:option:: name: label
+      :type: text
+
+      An implicit target name that can be referenced using :rst:role:`ref`.
+      This is a :dudir:`common option <common-options>`.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: caption: caption
+      :type: text
+
+      Add a caption above the included content.
+      If no argument is given, the filename is used as the caption.
+
+      .. versionadded:: 1.3
+
+   .. rubric:: Options for formatting
+
+   .. rst:directive:option:: dedent: number
+      :type: number or no value
+
+      Strip indentation characters from the included content.
+      When a number is given, the leading N characters are removed.
+      When no argument given, all common leading indentation is removed
+      (using :func:`textwrap.dedent`).
+
+      .. versionadded:: 1.3
+      .. versionchanged:: 3.5
+         Support automatic dedent.
+
+   .. rst:directive:option:: tab-width: N
+      :type: number
+
+      Expand tabs to N spaces.
+
+      .. versionadded:: 1.0
+
+   .. rst:directive:option:: encoding
+      :type: text
+
+      Explicitly specify the encoding of the file.
+      This overwrites the default encoding (:confval:`source_encoding`).
+      For example:
+
+      .. code-block:: rst
+
+         .. literalinclude:: example.txt
             :encoding: latin-1
 
-   The directive also supports including only parts of the file.  If it is a
+      .. versionadded:: 0.4.3
-   Python module, you can select a class, function or method to include using
+
-   the ``pyobject`` option::
+   .. rst:directive:option:: linenos
+      :type: no value
+
+      Show line numbers alongside the included content.
+      By default, line numbers are counted from 1.
+      This can be changed by the options ``:lineno-start:`` and ``:lineno-match:``.
+
+   .. rst:directive:option:: lineno-start: number
+      :type: number
+
+      Set line number for the first line to show.
+      If given, this automatically activates ``:linenos:``.
+
+   .. rst:directive:option:: lineno-match
+
+      When including only parts of a file and show the original line numbers.
+      This is only allowed only when the selection consists of contiguous lines.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: emphasize-lines: line numbers
+      :type: comma separated numbers
+
+      Emphasise particular lines of the included content.
+      For example:
+
+      .. code-block:: rst
+
+         .. literalinclude:: example.txt
+            :emphasize-lines: 1,2,4-6
+
+   .. rst:directive:option:: language: language
+      :type: text
+
+      Select a highlighting language (`Pygments lexer`_) different from
+      the current file's standard language
+      (set by :rst:dir:`highlight` or :confval:`highlight_language`).
+
+      .. _Pygments lexer: https://pygments.org/docs/lexers/
+
+   .. rst:directive:option:: force
+      :type: no value
+
+      Ignore minor errors in highlighting.
+
+      .. versionadded:: 2.1
+
+   .. rubric:: Options for selecting the content to include
+
+   .. rst:directive:option:: pyobject: object
+      :type: text
+
+      For Python files, only include the specified class, function or method:
+
+      .. code-block:: rst
 
          .. literalinclude:: example.py
             :pyobject: Timer.start
 
-   This would only include the code lines belonging to the ``start()`` method
+      .. versionadded:: 0.6
-   in the ``Timer`` class within the file.
 
-   Alternately, you can specify exactly which lines to include by giving a
+   .. rst:directive:option:: lines: line numbers
-   ``lines`` option::
+      :type: comma separated numbers
+
+      Specify exactly which lines to include::
 
          .. literalinclude:: example.py
             :lines: 1,3,5-10,20-
 
-   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
+      This includes line 1, line 3, lines 5 to 10, and line 20 to the end.
 
-   Another way to control which part of the file is included is to use the
+      .. versionadded:: 0.6
-   ``start-after`` and ``end-before`` options (or only one of them).  If
+
-   ``start-after`` is given as a string option, only lines that follow the
+   .. rst:directive:option:: start-at: text
-   first line containing that string are included.  If ``end-before`` is given
+                             start-after: text
-   as a string option, only lines that precede the first lines containing that
+                             end-before: text
-   string are included. The ``start-at`` and ``end-at`` options behave in a
+                             end-at: text
-   similar way, but the lines containing the matched string are included.
+
+      Another way to control which part of the file is included is to use
+      the ``start-after`` and ``end-before`` options (or only one of them).
+      If ``start-after`` is given as a string option,
+      only lines that follow the first line containing that string are included.
+      If ``end-before`` is given as a string option,
+      only lines that precede the first lines containing that string are included.
+      The ``start-at`` and ``end-at`` options behave in a similar way,
+      but the lines containing the matched string are included.
 
       ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string.
-   ``start-after``/``start-at`` filter lines before the line that contains
+      ``start-after``/``start-at`` filter lines before the line
-   option string (``start-at`` will keep the line). Then ``end-before``/``end-at``
+      that contains the option string
-   filter lines after the line that contains option string (``end-at`` will keep
+      (``start-at`` will keep the line).
-   the line and ``end-before`` skip the first line).
+      Then ``end-before``/``end-at`` filter lines after the line
+      that contains the option string
+      (``end-at`` will keep the line and ``end-before`` skip the first line).
 
-   .. note::
+      .. versionadded:: 0.6
+         Added the ``start-after`` and ``end-before`` options.
+      .. versionadded:: 1.5
+         Added the ``start-at``, and ``end-at`` options.
 
-      If you want to select only ``[second-section]`` of ini file like the
+      .. tip::
-      following, you can use ``:start-at: [second-section]`` and
+
-      ``:end-before: [third-section]``:
+         To only select ``[second-section]`` of an INI file such as the following,
+         use ``:start-at: [second-section]`` and ``:end-before: [third-section]``:
 
          .. code-block:: ini
 
             [first-section]
-
             var_in_first=true
 
             [second-section]
-
             var_in_second=true
 
             [third-section]
-
             var_in_third=true
 
-      Useful cases of these option is working with tag comments.
+         These options can be useful when working with tag comments.
-      ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options
+         Using ``:start-after: [initialise]`` and ``:end-before: [initialised]``
-      keep lines between comments:
+         keeps the lines between between the two comments below:
 
          .. code-block:: py
 
             if __name__ == "__main__":
-             # [initialize]
+                # [initialise]
                 app.start(":8000")
-             # [initialized]
+                # [initialised]
 
+         When lines have been selected in any of the ways described above,
+         the line numbers in ``emphasize-lines`` refer to these selected lines,
+         counted consecutively starting from 1.
 
-   When lines have been selected in any of the ways described above, the line
+   .. rst:directive:option:: prepend: line
-   numbers in ``emphasize-lines`` refer to those selected lines, counted
+      :type: text
-   consecutively starting at ``1``.
 
-   When specifying particular parts of a file to display, it can be useful to
+      Prepend a line before the included code.
-   display the original line numbers. This can be done using the
+      This can be useful for example when highlighting
-   ``lineno-match`` option, which is however allowed only when the selection
+      PHP code that doesn't include the ``<?php`` or ``?>`` markers.
-   consists of contiguous lines.
 
-   You can prepend and/or append a line to the included code, using the
+      .. versionadded:: 1.0
-   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
-   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
 
-   If you want to show the diff of the code, you can specify the old file by
+   .. rst:directive:option:: append: line
-   giving a ``diff`` option::
+      :type: text
 
-      .. literalinclude:: example.py
+      Append a line after the included code.
-         :diff: example.py.orig
+      This can be useful for example when highlighting
+      PHP code that doesn't include the ``<?php`` or ``?>`` markers.
 
-   This shows the diff between ``example.py`` and ``example.py.orig`` with
+      .. versionadded:: 1.0
-   unified diff format.
 
-   A ``force`` option can ignore minor errors on highlighting.
+   .. rst:directive:option:: diff: filename
 
-   .. versionchanged:: 0.4.3
+      Show the diff of two files.
-      Added the ``encoding`` option.
+      For example:
+
+      .. code-block:: rst
+
+         .. literalinclude:: example.txt
+            :diff: example.txt.orig
+
+      This shows the diff between ``example.txt`` and ``example.txt.orig``
+      with unified diff format.
+
+      .. versionadded:: 1.3
 
    .. versionchanged:: 0.6
-      Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before``
+      Added support for absolute filenames.
-      options, as well as support for absolute filenames.
-
-   .. versionchanged:: 1.0
-      Added the ``prepend``, ``append``, and ``tab-width`` options.
-
-   .. versionchanged:: 1.3
-      Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and
-      ``dedent`` options.
-
-   .. versionchanged:: 1.4
-      Added the ``class`` option.
-
-   .. versionchanged:: 1.5
-      Added the ``start-at``, and ``end-at`` options.
 
    .. versionchanged:: 1.6
-      With both ``start-after`` and ``lines`` in use, the first line as per
+      With both ``start-after`` and ``lines`` in use,
-      ``start-after`` is considered to be with line number ``1`` for ``lines``.
+      the first line as per ``start-after`` is considered to be
-
+      with line number ``1`` for ``lines``.
-   .. versionchanged:: 2.1
-      Added the ``force`` option.
-
-   .. versionchanged:: 3.5
-      Support automatic dedent.
 
 .. _glossary-directive: