Lists
=====

Bulleted lists
---------------
`Bulleted lists <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists>`_ are collections of items in which the order of the items does not matter. They are also called unordered lists.

To create a bulleted list:

* Use the symbols ``*``, ``+``, or ``-`` followed by at least one space. These are the standard markdown list symbols, but reST supports others. 
* Create sub-levels by indenting list items by at least four spaces.
* Maintain the same indentation for all items at the same level.
* The choice of symbol does not affect the output list style, which is determined solely by the indentation. 
* A blank line is required before the first item and after the last item for each level, but is optional between items at the same level.
* Include additional paragraphs of item text after a blank line and with the same indentation.

The following example creates a bulleted list with two sub-levels using multiple markers. ::

	* Lorem ipsum dolor sit amet, consectetur adipiscing elit.
	* Nullam eu ligula a nunc volutpat rutrum.

		+ Vestibulum placerat lacinia nibh.
		+ Donec suscipit eu metus sed porttitor.

			* Nunc arcu neque.
			* Donec sed lobortis odio.

	- Aenean eget sapien ligula.

	  Vivamus hendrerit sem nunc, sed tincidunt lorem volutpat venenatis.
 	  Quisque porttitor nulla neque, sed congue nulla dictum ut.

It is displayed as

* Lorem ipsum dolor sit amet, consectetur adipiscing elit.
* Nullam eu ligula a nunc volutpat rutrum.

	+ Vestibulum placerat lacinia nibh.
	+ Donec suscipit eu metus sed porttitor.

		* Nunc arcu neque.
		* Donec sed lobortis odio.

- Aenean eget sapien ligula.

  Vivamus hendrerit sem nunc, sed tincidunt lorem volutpat venenatis.
  Quisque porttitor nulla neque, sed congue nulla dictum ut.

Enumerated lists
----------------
`Enumerated lists <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists>`_ are collections of items in which the order of the items is important. They are also called ordered lists.

To create an enumerated list:

* Use numerals ``1, 2, 3, ...``, alphabetic characters upper case ``A, B, C, ...`` or lower case ``a, b, c, ...``, or roman numerals upper case ``I, II, III, ...`` or lower case ``i, ii, iii, ...``. You can also automatically enumerate lists using the hash symbol ``#``. 
* Specify a formatting type followed by at least one space. The formatting types include a period ``1., A., a., I., i.``, parentheses ``(1), (A), (a), (I), (i)``, and a right-parenthesis ``1), A), a), I), i)``.
* A new list is started when an enumerator is encountered that does not have the same format and sequence type as the current list (e.g. ``1., (a)``), or the enumerators are not in sequence (e.g. ``1., 3.``).
* Include blank lines consistent with the bulleted list rules.

.. highlight:: none

The following example creates an enumerated list with two sub-levels using multiple markers. ::

	1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
	2. Nullam eu ligula a nunc volutpat rutrum.

		(A) Vestibulum placerat lacinia nibh.
		(B) Donec suscipit eu metus sed porttitor.

			a) Nunc arcu neque.
			b) Donec sed lobortis odio.

	#. Aenean eget sapien ligula.

	  Vivamus hendrerit sem nunc, sed tincidunt lorem volutpat venenatis.
 	  Quisque porttitor nulla neque, sed congue nulla dictum ut.

.. highlight:: default

It is displayed as

1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2. Nullam eu ligula a nunc volutpat rutrum.

	(A) Vestibulum placerat lacinia nibh.
	(B) Donec suscipit eu metus sed porttitor.

		a) Nunc arcu neque. 
		b) Donec sed lobortis odio.

#. Aenean eget sapien ligula.

  Vivamus hendrerit sem nunc, sed tincidunt lorem volutpat venenatis.
  Quisque porttitor nulla neque, sed congue nulla dictum ut.

Definition lists
----------------
`Definition lists <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists>`_ associate terms with their definitions and are a convenient way to create a glossary.

To create a definition list:

* Specify each term as a one-line phrase. 
* Specify the definition using one or more paragraphs or body elements, and indented relative to the term. 
* Blank lines are not allowed between term and definition.
* Blank lines are required before the first and after the last definition list item, but are optional between list items. 

.. highlight:: none

The following example creates a two-item definition list. ::

	what
  		Definition lists associate a term with a definition.
	how
  		The term is a one-line phrase, and the definition is one or more paragraphs or
  		body elements, indented relative to the term. 

  		Blank lines are not allowed between term and definition.

.. highlight:: default

It is displayed as

what
  	Definition lists associate a term with a definition.
how
  	The term is a one-line phrase, and the definition is one or more paragraphs or
  	body elements, indented relative to the term. 

  	Blank lines are not allowed between term and definition.