Add support for :meta public:

A common use case for this is a class like `namedtuple`, which has a public `_replace` method that is so-named in order not to conflict with arbitrary user-provided attributes.

Rejected spellings include:
* `:meta not-private:`
* `:meta private: False`

doc/usage/extensions/autodoc.rst

@@ -154,6 +154,21 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 3.0
 
+   * autodoc considers a member public if its docstring contains
+     ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with
+     an underscore.
+     For example:
+
+     .. code-block:: rst
+
+        def _my_function(my_arg, my_other_arg):
+            """blah blah blah
+
+            :meta public:
+            """
+
+     .. versionadded:: 3.1
+
    * Python "special" members (that is, those named like ``__special__``) will
      be included if the ``special-members`` flag option is given::
 

sphinx/ext/autodoc/__init__.py

@@ -574,6 +574,9 @@ class Documenter:
             if 'private' in metadata:
                 # consider a member private if docstring has "private" metadata
                 isprivate = True
+            elif 'public' in metadata:
+                # consider a member public if docstring has "public" metadata
+                isprivate = False
             else:
                 isprivate = membername.startswith('_')
 

tests/roots/test-ext-autodoc/target/private.py

@@ -3,3 +3,9 @@ def private_function(name):
 
     :meta private:
     """
+
+def _public_function(name):
+    """public_function is a docstring().
+
+    :meta public:
+    """

tests/test_ext_autodoc_private_members.py

@@ -22,6 +22,14 @@ def test_private_field(app):
         '',
         '.. py:module:: target.private',
         '',
+        '',
+        '.. py:function:: _public_function(name)',
+        '   :module: target.private',
+        '',
+        '   public_function is a docstring().',
+        '',
+        '   :meta public:',
+        '',
     ]
 
 
@@ -36,6 +44,14 @@ def test_private_field_and_private_members(app):
         '.. py:module:: target.private',
         '',
         '',
+        '.. py:function:: _public_function(name)',
+        '   :module: target.private',
+        '',
+        '   public_function is a docstring().',
+        '',
+        '   :meta public:',
+        '',
+        '',
         '.. py:function:: private_function(name)',
         '   :module: target.private',
         '',