Deprecate suffix for env.doc2path()

CHANGES

@@ -15,6 +15,7 @@ Incompatible changes
 Deprecated
 ----------
 
+* The ``suffix`` argument of ``env.doc2path()`` is deprecated.
 * ``sphinx.ext.doctest.doctest_encode()``
 * ``sphinx.testing.util.remove_unicode_literal()``
 

doc/extdev/index.rst

@@ -116,6 +116,11 @@ The following is a list of deprecated interface.
      - (will be) Removed
      - Alternatives
 
+   * - ``suffix`` argument of ``BuildEnvironment.doc2path()``
+     - 2.0
+     - 4.0
+     - N/A
+
    * - ``sphinx.ext.doctest.doctest_encode()``
      - 2.0
      - 4.0

sphinx/builders/__init__.py

@@ -536,7 +536,7 @@ class Builder(object):
         doctree.settings.env = None
         doctree.settings.record_dependencies = None
 
-        doctree_filename = self.env.doc2path(docname, self.env.doctreedir, '.doctree')
+        doctree_filename = path.join(self.doctreedir, docname + '.doctree')
         ensuredir(path.dirname(doctree_filename))
         with open(doctree_filename, 'wb') as f:
             pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)

sphinx/builders/text.py

@@ -50,8 +50,7 @@ class TextBuilder(Builder):
             if docname not in self.env.all_docs:
                 yield docname
                 continue
-            targetname = self.env.doc2path(docname, self.outdir,
-                                           self.out_suffix)
+            targetname = path.join(self.outdir, docname + self.out_suffix)
             try:
                 targetmtime = path.getmtime(targetname)
             except Exception:

sphinx/builders/xml.py

@@ -53,8 +53,7 @@ class XMLBuilder(Builder):
             if docname not in self.env.all_docs:
                 yield docname
                 continue
-            targetname = self.env.doc2path(docname, self.outdir,
-                                           self.out_suffix)
+            targetname = path.join(self.outdir, docname + self.out_suffix)
             try:
                 targetmtime = path.getmtime(targetname)
             except Exception:

sphinx/environment/__init__.py

@@ -20,7 +20,7 @@ from six import BytesIO, next
 from six.moves import cPickle as pickle
 
 from sphinx import addnodes
-from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.errors import SphinxError, BuildEnvironmentError, DocumentError, ExtensionError
 from sphinx.locale import __
@@ -339,6 +339,10 @@ class BuildEnvironment(object):
         If *base* is a path string, return absolute path under that.
         If *suffix* is not None, add it instead of config.source_suffix.
         """
+        if suffix:
+            warnings.warn('The suffix argument for doc2path() is deprecated.',
+                          RemovedInSphinx40Warning)
+
         docname = docname.replace(SEP, path.sep)
         if suffix is None:
             # Use first candidate if there is not a file for any suffix
@@ -438,8 +442,8 @@ class BuildEnvironment(object):
                     added.add(docname)
                     continue
                 # if the doctree file is not there, rebuild
-                if not path.isfile(self.doc2path(docname, self.doctreedir,
-                                                 '.doctree')):
+                filename = path.join(self.doctreedir, docname + '.doctree')
+                if not path.isfile(filename):
                     changed.add(docname)
                     continue
                 # check the "reread always" list
@@ -553,8 +557,8 @@ class BuildEnvironment(object):
     def get_doctree(self, docname):
         # type: (unicode) -> nodes.Node
         """Read the doctree for a file from the pickle and return it."""
-        doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
-        with open(doctree_filename, 'rb') as f:
+        filename = path.join(self.doctreedir, docname + '.doctree')
+        with open(filename, 'rb') as f:
             doctree = pickle.load(f)
         doctree.settings.env = self
         doctree.reporter = LoggingReporter(self.doc2path(docname))

sphinx/versioning.py

@@ -12,6 +12,7 @@
 import warnings
 from itertools import product
 from operator import itemgetter
+from os import path
 from uuid import uuid4
 
 from six.moves import cPickle as pickle
@@ -168,7 +169,7 @@ class UIDTransform(SphinxTransform):
         if env.versioning_compare:
             # get old doctree
             try:
-                filename = env.doc2path(env.docname, env.doctreedir, '.doctree')
+                filename = path.join(env.doctreedir, env.docname + '.doctree')
                 with open(filename, 'rb') as f:
                     old_doctree = pickle.load(f)
             except EnvironmentError: