From fa560ebf958e0319353db1da04e36ccef45c76c4 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Sat, 4 May 2019 17:26:26 +0900
Subject: [PATCH] apidoc: Deprecate unused functions

---
 CHANGES                   | 2 ++
 doc/extdev/deprecated.rst | 9 +++++++++
 sphinx/ext/apidoc.py      | 6 ++++++
 3 files changed, 17 insertions(+)

diff --git a/CHANGES b/CHANGES
index 8a7c6647b..e9ba00d96 100644
--- a/CHANGES
+++ b/CHANGES
@@ -41,6 +41,8 @@ Deprecated
 * ``sphinx.domains.std.StandardDomain.note_citation_refs()``
 * ``sphinx.domains.std.StandardDomain.note_labels()``
 * ``sphinx.environment.NoUri``
+* ``sphinx.ext.apidoc.format_directive()``
+* ``sphinx.ext.apidoc.format_heading()``
 * ``sphinx.ext.autodoc.importer.MockFinder``
 * ``sphinx.ext.autodoc.importer.MockLoader``
 * ``sphinx.ext.autodoc.importer.mock()``
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 6e9ce34f0..2ecb1e2e7 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -161,6 +161,15 @@ The following is a list of deprecated interfaces.
      - 2.1
      - 4.0
      - ``sphinx.errors.NoUri``
+   * - ``sphinx.ext.apidoc.format_directive()``
+     - 2.1
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.apidoc.format_heading()``
+     - 2.1
+     - 4.0
+     - N/A
 
    * - ``sphinx.ext.autodoc.importer.MockFinder``
      - 2.1
diff --git a/sphinx/ext/apidoc.py b/sphinx/ext/apidoc.py
index af77133b2..2243e0644 100644
--- a/sphinx/ext/apidoc.py
+++ b/sphinx/ext/apidoc.py
@@ -19,12 +19,14 @@ import glob
 import locale
 import os
 import sys
+import warnings
 from fnmatch import fnmatch
 from os import path
 
 import sphinx.locale
 from sphinx import __display_version__, package_dir
 from sphinx.cmd.quickstart import EXTENSIONS
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.locale import __
 from sphinx.util import rst
 from sphinx.util.osutil import FileAvoidWrite, ensuredir
@@ -82,6 +84,8 @@ def write_file(name, text, opts):
 def format_heading(level, text, escape=True):
     # type: (int, str, bool) -> str
     """Create a heading of <level> [1, 2 or 3 supported]."""
+    warnings.warn('format_warning() is deprecated.',
+                  RemovedInSphinx40Warning)
     if escape:
         text = rst.escape(text)
     underlining = ['=', '-', '~', ][level - 1] * len(text)
@@ -91,6 +95,8 @@ def format_heading(level, text, escape=True):
 def format_directive(module, package=None):
     # type: (str, str) -> str
     """Create the automodule directive and add the options."""
+    warnings.warn('format_directive() is deprecated.',
+                  RemovedInSphinx40Warning)
     directive = '.. automodule:: %s\n' % makename(package, module)
     for option in OPTIONS:
         directive += '    :%s:\n' % option