From 0d7451c23d9250e4c681ca5acf860fec03edfb42 Mon Sep 17 00:00:00 2001
From: Eric Wieser <wieser.eric@gmail.com>
Date: Mon, 13 Apr 2020 15:55:07 +0100
Subject: [PATCH] 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               | 15 +++++++++++++++
 sphinx/ext/autodoc/__init__.py                 |  3 +++
 tests/roots/test-ext-autodoc/target/private.py |  6 ++++++
 tests/test_ext_autodoc_private_members.py      | 16 ++++++++++++++++
 4 files changed, 40 insertions(+)

diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 60cde1ac7..36be7568b 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/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::
 
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index ac4c7ed4b..89a8b5c70 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/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('_')
 
diff --git a/tests/roots/test-ext-autodoc/target/private.py b/tests/roots/test-ext-autodoc/target/private.py
index 38f276663..a39ce085e 100644
--- a/tests/roots/test-ext-autodoc/target/private.py
+++ b/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:
+    """
diff --git a/tests/test_ext_autodoc_private_members.py b/tests/test_ext_autodoc_private_members.py
index 2d9208b41..befcac396 100644
--- a/tests/test_ext_autodoc_private_members.py
+++ b/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',
         '',