Fix shared-CONSTANTS state leaks in doctests, wire up doctest CI

Several docstring/doc examples mutated the shared CONSTANTS singleton
(capitalize_name, force_mixed_case_capitalization, empty_attribute_default,
titles.clear()) without resetting it. Since Sphinx's doctest groups only
isolate local variables, not global state, these leaked forward into later
examples across the whole doc build in an order-dependent way -- causing
wrong capitalization in the nicknames example, as_dict() returning None,
"Sir" leaking into first_list once titles was cleared, and more.

- nameparser/config/__init__.py: reset CONSTANTS after each docstring demo;
  make SetManager.__repr__ sort elements so it's deterministic across
  processes (previously relied on set() iteration order, which varies with
  string hash randomization)
- docs/usage.rst: reset CONSTANTS.capitalize_name /
  force_mixed_case_capitalization after their demo blocks
- docs/customize.rst: switch the "Hon" removal/clear-titles demo to a
  local Constants() instance instead of the shared singleton (it isn't
  actually demonstrating shared-singleton behavior, so there's no need to
  mutate global state); fix the emoji example to call str(hn) instead of
  showing hn's repr; update the SetManager ellipsis examples to match the
  now-sorted repr

All 186 Sphinx doctests and the 10 README.rst doctests now pass (previously
multiple failures across usage.rst, customize.rst, and parser.py's own
docstrings). Wired both into CI (.github/workflows/python-package.yml) so
this doesn't silently regress again.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: derek73

.github/workflows/python-package.yml

@@ -44,3 +44,5 @@ jobs:
         python -m build --sdist
         twine check dist/*
         sphinx-build -b html docs dist/docs
+        sphinx-build -b doctest docs dist/doctest
+        python -m doctest README.rst

docs/customize.rst

@@ -345,7 +345,9 @@ constant so that "Hon" can be parsed as a first name.
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
-    >>> hn = HumanName("Hon Solo")
+    >>> from nameparser.config import Constants
+    >>> constants = Constants()
+    >>> hn = HumanName("Hon Solo", constants=constants)
     >>> hn
     <HumanName : [
         title: 'Hon'
@@ -356,10 +358,9 @@ constant so that "Hon" can be parsed as a first name.
         nickname: ''
         maiden: ''
     ]>
-    >>> from nameparser.config import CONSTANTS
-    >>> CONSTANTS.titles.remove('hon')
-    SetManager({'right', ..., 'tax'})
-    >>> hn = HumanName("Hon Solo")
+    >>> constants.titles.remove('hon')
+    SetManager({'10th', ..., 'zoologist'})
+    >>> hn = HumanName("Hon Solo", constants=constants)
     >>> hn
     <HumanName : [
         title: ''
@@ -374,7 +375,11 @@ constant so that "Hon" can be parsed as a first name.
 
 If you don't want to detect any titles at all, you can remove all of them:
 
-    >>> CONSTANTS.titles.clear()
+.. doctest::
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
+
+    >>> constants.titles.clear()
+    SetManager(set())
 
 
 Adding a Title
@@ -399,7 +404,7 @@ making them lower case and removing periods.
     >>> from nameparser.config import Constants
     >>> constants = Constants()
     >>> constants.titles.add('dean', 'Chemistry')
-    SetManager({'right', ..., 'tax'})
+    SetManager({'10th', ..., 'zoologist'})
     >>> hn = HumanName("Assoc Dean of Chemistry Robert Johns", constants=constants)
     >>> hn
     <HumanName : [
@@ -427,7 +432,7 @@ the config on one instance could modify the behavior of another instance.
     >>> from nameparser import HumanName
     >>> instance = HumanName("")
     >>> instance.C.titles.add('dean')
-    SetManager({'right', ..., 'tax'})
+    SetManager({'10th', ..., 'zoologist'})
     >>> other_instance = HumanName("Dean Robert Johns")
     >>> other_instance # Dean parses as title
     <HumanName : [
@@ -455,7 +460,7 @@ reference to the module-level config values with the behavior described above.
     >>> instance.has_own_config
     False
     >>> instance.C.titles.add('dean')
-    SetManager({'right', ..., 'tax'})
+    SetManager({'10th', ..., 'zoologist'})
     >>> other_instance = HumanName("Dean Robert Johns", None) # <-- pass None for per-instance config
     >>> other_instance
     <HumanName : [
@@ -483,8 +488,8 @@ You can turn this off by setting the ``emoji`` regex to ``False``.
     >>> constants = Constants()
     >>> constants.regexes.emoji = False
     >>> hn = HumanName("Sam 😊 Smith", constants=constants)
-    >>> hn
-    "Sam 😊 Smith"
+    >>> str(hn)
+    'Sam 😊 Smith'
 
 Config Changes May Need Parse Refresh
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -529,9 +534,9 @@ directly to the attribute.
   >>> hn = HumanName("Dr. John A. Kenneth Doe")
   >>> hn.title = ["Associate","Professor"]
   >>> hn.suffix = "Md."
-  >>> hn.suffix
+  >>> hn
   <HumanName : [
-      title: 'Associate Processor'
+      title: 'Associate Professor'
       first: 'John'
       middle: 'A. Kenneth'
       last: 'Doe'

docs/usage.rst

@@ -112,6 +112,7 @@ To apply capitalization to all `HumanName` instances, set
     >>> name = HumanName("bob v. de la macdole-eisenhower phd")
     >>> str(name)
     'Bob V. de la MacDole-Eisenhower Ph.D.'
+    >>> CONSTANTS.capitalize_name = False
 
 To force the capitalization of mixed case strings on all `HumanName` instances,
 set :py:attr:`~nameparser.config.Constants.force_mixed_case_capitalization` to `True`. 
@@ -125,6 +126,7 @@ set :py:attr:`~nameparser.config.Constants.force_mixed_case_capitalization` to `
     >>> name.capitalize()
     >>> str(name)
     'Shirley MacLaine'
+    >>> CONSTANTS.force_mixed_case_capitalization = False
 
 
 Nickname Handling

nameparser/config/__init__.py

@@ -75,7 +75,10 @@ def __call__(self) -> Set[str]:
         return self.elements
 
     def __repr__(self) -> str:
-        return f"SetManager({self.elements})"  # used for docs
+        # Sorted so repr is stable across runs -- set() iteration order
+        # depends on string hash randomization, which varies per process.
+        elements = "{" + ", ".join(repr(e) for e in sorted(self.elements)) + "}" if self.elements else "set()"
+        return f"SetManager({elements})"  # used for docs
 
     def __iter__(self) -> Iterator[str]:
         return iter(self.elements)
@@ -363,6 +366,7 @@ class Constants:
         None
         >>> name.first
         'John'
+        >>> CONSTANTS.empty_attribute_default = ''
 
     """
 
@@ -378,6 +382,7 @@ class Constants:
         >>> name = HumanName("bob v. de la macdole-eisenhower phd")
         >>> str(name)
         'Bob V. de la MacDole-Eisenhower Ph.D.'
+        >>> CONSTANTS.capitalize_name = False
 
     """
 
@@ -394,6 +399,7 @@ class Constants:
         >>> name.capitalize()
         >>> str(name)
         'Shirley MacLaine'
+        >>> CONSTANTS.force_mixed_case_capitalization = False
 
     """