pyparsing
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 93 additions & 26 deletions b/‎CONTRIBUTING.md‎
Lines changed: 93 additions & 26 deletions
@@ -38,41 +38,49 @@ If you have a question on using pyparsing, there are a number of resources avail
 
 If you have an example you wish to submit, please follow these guidelines.
 
-- **License - Submitted example code must be available for distribution with the rest of pyparsing under the MIT 
+- **License - Submitted example code must be available for distribution with the rest of pyparsing under the MIT
   open source license.**
 
 - Please follow PEP8 name and coding guidelines, and use the black formatter
-  to auto-format code. 
+  to auto-format code.
 
 - Examples should import pyparsing and the common namespace classes as:
 
-      import pyparsing as pp
-      # if necessary
-      ppc = pp.pyparsing_common
-      ppu = pp.pyparsing_unicode
+  ```python
+  import pyparsing as pp
+  # if necessary
+  ppc = pp.pyparsing_common
+  ppu = pp.pyparsing_unicode
+  ```
 
-- Submitted examples *must* be Python 3.6.8 or later compatible. (It is acceptable if examples use Python
-  features added after 3.6)
+- Submitted examples _must_ be Python 3.6.8 or later compatible.
+  (It is acceptable if examples use Python features added after 3.6)
 
 - Where possible use operators to create composite parse expressions:
 
-      expr = expr_a + expr_b | expr_c
+  ```python
+  expr = expr_a + expr_b | expr_c
+  ```
 
   instead of:
 
-      expr = pp.MatchFirst([pp.And([expr_a, expr_b]), expr_c])
+  ```python
+  expr = pp.MatchFirst([pp.And([expr_a, expr_b]), expr_c])
+  ```
 
   Exception: if using a generator to create an expression:
 
-      import keyword
-      python_keywords = keyword.kwlist
-      any_keyword = pp.MatchFirst(pp.Keyword(kw)
-                                  for kw in python_keywords))
+  ```python
+  import keyword
+  python_keywords = keyword.kwlist
+  any_keyword = pp.MatchFirst(pp.Keyword(kw)
+                              for kw in python_keywords))
+  ```
 
-- Learn [Common Pitfalls When Writing Parsers](https://github.com/pyparsing/pyparsing/wiki/Common-Pitfalls-When-Writing-Parsers) and
+- Learn [Common Pitfalls When Writing Parsers][pitfalls] and
   how to avoid them when developing new examples.
 
-- See additional notes under [Some Coding Points](#some-coding-points).
+- See additional notes under [Some coding points](#some-coding-points).
 
 ## Submitting changes
 
@@ -88,11 +96,11 @@ intended on prior versions of Python (currently back to Python 3.6.8).
 
 ## Some design points
 
-- Minimize additions to the module namespace. Over time, pyparsing's namespace has acquired a *lot* of names.
+- Minimize additions to the module namespace. Over time, pyparsing's namespace has acquired a _lot_ of names.
   New features have been encapsulated into namespace classes to try to hold back the name flooding when importing
   pyparsing.
 
-- New operator overloads for ParserElement will need to show broad applicability, and should be related to 
+- New operator overloads for ParserElement will need to show broad applicability, and should be related to
   parser construction.
 
 - Performance tuning should focus on parse time performance. Optimizing parser definition performance is secondary.
@@ -108,28 +116,87 @@ These coding styles are encouraged whether submitting code for core pyparsing or
   name casing. I had just finished several years of Java and Smalltalk development, and camel case seemed to be the
   future trend in coding styles. As of version 3.0.0, pyparsing is moving over to PEP8 naming, while maintaining
   compatibility with existing parser code by defining synonyms using the legacy names. These names will be
-  retained until a future release (probably 4.0), to provide a migration path for current pyparsing-dependent 
+  retained until a future release (probably 4.0), to provide a migration path for current pyparsing-dependent
   applications - DO NOT MODIFY OR REMOVE THESE NAMES.
   See more information at the [PEP8 wiki page](https://github.com/pyparsing/pyparsing/wiki/PEP-8-planning).
 
 - No backslashes for line continuations.
-  Continuation lines for expressions in ()'s should start with the continuing operator:
+  Continuation lines for expressions in `()`'s should start with the continuing operator:
 
-      really_long_line = (something
-                          + some_other_long_thing
-                          + even_another_long_thing)
+  ```python
+  really_long_line = (something
+                      + some_other_long_thing
+                      + even_another_long_thing)
+  ```
 
 - Maximum line length is 120 characters. (Black will override this.)
 
 - Changes to core pyparsing must be compatible back to Py3.6 without conditionalizing. Later Py3 features may be
   used in examples by way of illustration.
 
-- str.format() statements should use named format arguments (unless this proves to be a slowdown at parse time).
+- `str.format()` statements should use named format arguments (unless this proves to be a slowdown at parse time).
 
 - List, tuple, and dict literals should include a trailing comma after the last element, which reduces changeset
   clutter when another element gets added to the end.
 
-- New features should be accompanied by updates to unitTests.py and a bullet in the CHANGES file.
+- New features should be accompanied by updates to `unitTests.py` and a bullet in the CHANGES file.
 
-- Do not modify pyparsing_archive.py. This file is kept as a reference artifact from when pyparsing was distributed
+- Do not modify `pyparsing_archive.py`. This file is kept as a reference artifact from when pyparsing was distributed
   as a single source file.
+
+## Some documentation points
+
+- The docstrings in pyparsing (which are generated into the package's
+  API documentation by Sphinx) make heavy use of doctests for their
+  example code. This allows examples to be tested and verified as
+  working, and ensures that any changes to the code which affect
+  output are accompanied by corresponding changes in the examples.
+
+- The codebase's docstring tests can be verified by running the
+  command `make doctest` from the `docs/` directory. The output
+  should ideally look something like this:
+
+  ```console
+  $ make doctest
+  [...documentation build...]
+  running tests...
+
+  Document: pyparsing
+  -------------------
+  1 item passed all tests:
+   204 tests in default
+  204 tests in 1 item.
+  204 passed.
+  Test passed.
+
+  Document: whats_new_in_3_1
+  --------------------------
+  1 item passed all tests:
+    15 tests in default
+  15 tests in 1 item.
+  15 passed.
+  Test passed.
+
+  Doctest summary
+  ===============
+    219 tests
+      0 failures in tests
+      0 failures in setup code
+      0 failures in cleanup code
+  ```
+
+  Any failed tests will be displayed in detail.
+
+- Much more information about doctests can be found in the
+  [Pyparsing documentation][pyparsing-docs], in the chapter titled
+  "Writing doctest examples". Even if you have never worked with them
+  before, it should guide you through everything you need to know in
+  order to write Pyparsing doctest examples. If you are already familiar
+  with doctests and with `sphinx.ext.doctest` in general, you may wish
+  to skip over the introductory content and go straight to the section
+  on "Doctests in Pyparsing" which covers some issues specific to the
+  project.
+
+<!-- Named hyperlink targets, used in the preceding text -->
+[pitfalls]: https://github.com/pyparsing/pyparsing/wiki/Common-Pitfalls-When-Writing-Parsers
+[pyparsing-docs]: https://pyparsing-docs.readthedocs.io/en/latest/