sphinx-build: Move code out of 'sphinx.__init__'

We have multiple executables in tree and, while 'sphinx-build' is
arguably the most important of these, there's no reason its importance
should warrant inclusion at the package level.

Create a new module, 'sphinx.cmd', and move the code from
'sphinx.__init__' into a 'build' submodule within. This name might be a
bit disingenuous at present, given the availability of 'make-mode' here
too, but that's an artifact of the current executable design and can be
cleaned up later.

To avoid breaking packages that are using this feature directly, aliases
for the old 'main' method are included. This is based on what Django
does [1] and, like Django, will allow us to safely remove the old
modules in Sphinx 2.0.

[1] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695

Signed-off-by: Stephen Finucane <stephen@that.guru>

setup.py

@@ -239,7 +239,7 @@ setup(
     include_package_data=True,
     entry_points={
         'console_scripts': [
-            'sphinx-build = sphinx:main',
+            'sphinx-build = sphinx.cmd.build:main',
             'sphinx-quickstart = sphinx.quickstart:main',
             'sphinx-apidoc = sphinx.ext.apidoc:main',
             'sphinx-autogen = sphinx.ext.autosummary.generate:main',

sphinx/__init__.py

@@ -15,15 +15,12 @@
 from __future__ import absolute_import
 
 import os
-import sys
 import warnings
 from os import path
 
+from .cmd import build
 from .deprecation import RemovedInNextVersionWarning
-
-if False:
-    # For type annotation
-    from typing import List  # NOQA
+from .deprecation import RemovedInSphinx20Warning
 
 # by default, all DeprecationWarning under sphinx package will be emit.
 # Users can avoid this by using environment variable: PYTHONWARNINGS=
@@ -63,27 +60,19 @@ if __version__.endswith('+'):
         pass
 
 
-def main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
-    if sys.argv[1:2] == ['-M']:
-        return make_main(argv)
-    else:
-        return build_main(argv)
-
-
-def build_main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
-    """Sphinx build "main" command-line entry."""
-    from sphinx import cmdline
-    return cmdline.main(argv)  # type: ignore
-
-
-def make_main(argv=sys.argv[1:]):
-    # type: (List[str]) -> int
-    """Sphinx build "make mode" entry."""
-    from sphinx import make_mode
-    return make_mode.run_make_mode(argv[1:])  # type: ignore
+def main(*args, **kwargs):
+    warnings.warn(
+        '`sphinx.main()` has moved to `sphinx.cmd.build.main()`.',
+        RemovedInSphinx20Warning,
+        stacklevel=2,
+    )
+    build.main(*args, **kwargs)
 
 
 if __name__ == '__main__':
-    sys.exit(main(sys.argv[1:]))
+    warnings.warn(
+        '`sphinx` has moved to `sphinx.build`.',
+        RemovedInSphinx20Warning,
+        stacklevel=2,
+    )
+    build.main()

sphinx/cmd/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.cmd
+    ~~~~~~~~~~
+
+    Modules for command line executables.
+
+    :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""

sphinx/cmd/build.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.cmd.build
+    ~~~~~~~~~~~~~~~~
+
+    Build documentation from a provided source.
+
+    :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import sys
+
+if False:
+    # For type annotation
+    from typing import List  # NOQA
+
+
+def build_main(argv=sys.argv[1:]):
+    # type: (List[str]) -> int
+    """Sphinx build "main" command-line entry."""
+    from sphinx import cmdline
+    return cmdline.main(argv)  # type: ignore
+
+
+def make_main(argv=sys.argv[1:]):
+    # type: (List[str]) -> int
+    """Sphinx build "make mode" entry."""
+    from sphinx import make_mode
+    return make_mode.run_make_mode(argv[1:])  # type: ignore
+
+
+def main(argv=sys.argv[1:]):
+    # type: (List[str]) -> int
+    if sys.argv[1:2] == ['-M']:
+        return make_main(argv)
+    else:
+        return build_main(argv)
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))