Document non_first_name_prefixes and log 1.3.0 entry (#121)

Author: derek73

docs/customize.rst

@@ -295,6 +295,33 @@ You can also pass a custom set per ``Constants`` instance::
     >>> hn2.first, hn2.last
     ('abu bakr', 'al saud')
 
+Non-First-Name Prefixes
+-----------------------
+
+``CONSTANTS.non_first_name_prefixes`` is the subset of prefixes that are *never*
+a standalone first name (``de``, ``dos``, ``ibn``, ...). When a name **starts**
+with one of these, there is no first name -- the whole thing is a surname.
+
+Example::
+
+    >>> from nameparser import HumanName
+    >>> hn = HumanName("de Mesnil")
+    >>> hn.first, hn.last
+    ('', 'de Mesnil')
+
+A member must be a prefix that is never a given name in any culture, and the set
+must stay **disjoint** from ``first_name_prefixes`` (a word cannot both join to
+the first name and never be a first name). Ambiguous particles that *can* be
+given names (``van``, ``von``, ``della``, ``di``, ``del``, ...) are intentionally
+excluded; add them yourself if your data warrants it::
+
+    >>> from nameparser.config import CONSTANTS
+    >>> CONSTANTS.non_first_name_prefixes.add('von')  # doctest: +SKIP
+
+To **disable** the feature entirely::
+
+    >>> CONSTANTS.non_first_name_prefixes.clear()  # doctest: +SKIP
+
 Parser Customization Examples
 -----------------------------
 

docs/release_log.rst

@@ -7,6 +7,7 @@ Release Log
     to 1.2.1 first (which includes a one-version compatibility shim), load and
     re-pickle under 1.2.1, then upgrade to 1.3.0.
 
+    - Add ``non_first_name_prefixes`` to ``Constants``: a leading particle that is never a first name (e.g. ``"de Mesnil"``, ``"dos Santos"``) now parses as a surname with an empty first name, instead of treating the particle as the first name (closes #121)
     - Add a first-class ``maiden`` field and ``maiden_delimiters`` to ``Constants``, so a delimiter (e.g. parenthesis) can be routed to ``maiden`` instead of ``nickname`` for alternate/maiden surnames, e.g. ``"Baker (Johnson), Jenny"`` (closes #22)
     - Fix suffix-shaped parenthesized/quoted content (e.g. ``"(Ret)"``, ``"(MBA)"``) being misclassified as a nickname instead of a suffix (closes #111)
     - Add ``suffix_acronyms_ambiguous`` to ``Constants`` for acronym suffixes that also read as given-name nicknames (e.g. ``"JD"``, ``"Ed"``), used when disambiguating parenthesized/quoted content (#111)