Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time r=mshal
authorAndrew Halberstadt <ahalberstadt@mozilla.com>
Fri, 06 Apr 2018 10:30:31 -0400
changeset 468196 15a5e48d01a51dc1b493074443af4021f4133d91
parent 468195 1b366ada7c5dd408e6053a61cf3b729e8d397605
child 468197 d34cf7a17b3bed597b611413fb73ad7f0f8a5d1d
push id9165
push userasasaki@mozilla.com
push dateThu, 26 Apr 2018 21:04:54 +0000
treeherdermozilla-beta@064c3804de2e [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmshal
bugs1410424
milestone61.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time r=mshal This removes the ability to specify multiple doc paths at the same time with |mach doc|. We will be changing the default from opening index files to serving the documentation with a webserver. Supporting multiple doc roots would mean spinning up multiple servers in different threads. This would add a lot of complexity for a feature which I don't think is very useful. It's very rare that one would need to edit more than one doc location at the same time. And if this is ever needed, the developer can just build the entire doctree (by running |mach doc|) or run |mach doc <path>| in multiple different terminals. MozReview-Commit-ID: GXEZJSgLpgF
tools/docs/mach_commands.py
--- a/tools/docs/mach_commands.py
+++ b/tools/docs/mach_commands.py
@@ -22,98 +22,86 @@ here = os.path.abspath(os.path.dirname(_
 
 
 @CommandProvider
 class Documentation(MachCommandBase):
     """Helps manage in-tree documentation."""
 
     @Command('doc', category='devenv',
              description='Generate and display documentation from the tree.')
-    @CommandArgument('what', nargs='*', metavar='DIRECTORY [, DIRECTORY]',
-                     help='Path(s) to documentation to build and display.')
+    @CommandArgument('path', default=None, metavar='DIRECTORY', nargs='?',
+                     help='Path to documentation to build and display.')
     @CommandArgument('--format', default='html',
                      help='Documentation format to write.')
     @CommandArgument('--outdir', default=None, metavar='DESTINATION',
                      help='Where to write output.')
     @CommandArgument('--archive', action='store_true',
                      help='Write a gzipped tarball of generated docs')
     @CommandArgument('--no-open', dest='auto_open', default=True,
                      action='store_false',
                      help="Don't automatically open HTML docs in a browser.")
     @CommandArgument('--http', const=':6666', metavar='ADDRESS', nargs='?',
                      help='Serve documentation on an HTTP server, '
                           'e.g. ":6666".')
     @CommandArgument('--upload', action='store_true',
                      help='Upload generated files to S3')
-    def build_docs(self, what=None, format=None, outdir=None, auto_open=True,
+    def build_docs(self, path=None, format=None, outdir=None, auto_open=True,
                    http=None, archive=False, upload=False):
         try:
             which.which('jsdoc')
         except which.WhichError:
             return die('jsdoc not found - please install from npm.')
 
         self._activate_virtualenv()
         self.virtualenv_manager.install_pip_requirements(
             os.path.join(here, 'requirements.txt'), quiet=True)
 
         import sphinx
         import webbrowser
         import moztreedocs
 
-        if not outdir:
-            outdir = os.path.join(self.topobjdir, 'docs')
-        if not what:
-            what = [os.path.join(self.topsrcdir, 'tools')]
-
+        outdir = outdir or os.path.join(self.topobjdir, 'docs')
         format_outdir = os.path.join(outdir, format)
 
-        generated = []
-        failed = []
-        for path in what:
-            path = os.path.normpath(os.path.abspath(path))
-            docdir = self._find_doc_dir(path)
+        path = path or os.path.join(self.topsrcdir, 'tools')
+        path = os.path.normpath(os.path.abspath(path))
 
-            if not docdir:
-                failed.append((path, 'could not find docs at this location'))
-                continue
+        docdir = self._find_doc_dir(path)
+        if not docdir:
+            return die('failed to generate documentation:\n'
+                       '%s: could not find docs at this location' % path)
 
-            props = self._project_properties(docdir)
-            savedir = os.path.join(format_outdir, props['project'])
+        props = self._project_properties(docdir)
+        savedir = os.path.join(format_outdir, props['project'])
 
-            args = [
-                'sphinx',
-                '-b', format,
-                docdir,
-                savedir,
-            ]
-            result = sphinx.build_main(args)
-            if result != 0:
-                failed.append((path, 'sphinx return code %d' % result))
-            else:
-                generated.append(savedir)
+        args = [
+            'sphinx',
+            '-b', format,
+            docdir,
+            savedir,
+        ]
+        result = sphinx.build_main(args)
+        if result != 0:
+            return die('failed to generate documentation:\n'
+                       '%s: sphinx return code %d' % (path, result))
+        else:
+            print('\nGenerated documentation:\n%s' % savedir)
 
-            if archive:
-                archive_path = os.path.join(outdir,
-                                            '%s.tar.gz' % props['project'])
-                moztreedocs.create_tarball(archive_path, savedir)
-                print('Archived to %s' % archive_path)
-
-            if upload:
-                self._s3_upload(savedir, props['project'], props['version'])
+        if archive:
+            archive_path = os.path.join(outdir,
+                                        '%s.tar.gz' % props['project'])
+            moztreedocs.create_tarball(archive_path, savedir)
+            print('Archived to %s' % archive_path)
 
-            index_path = os.path.join(savedir, 'index.html')
-            if not http and auto_open and os.path.isfile(index_path):
-                webbrowser.open(index_path)
+        if upload:
+            self._s3_upload(savedir, props['project'], props['version'])
 
-        if generated:
-            print('\nGenerated documentation:\n%s\n' % '\n'.join(generated))
-
-        if failed:
-            failed = ['%s: %s' % (f[0], f[1]) for f in failed]
-            return die('failed to generate documentation:\n%s' % '\n'.join(failed))
+        index_path = os.path.join(savedir, 'index.html')
+        if not http and auto_open and os.path.isfile(index_path):
+            webbrowser.open(index_path)
 
         if http is not None:
             host, port = http.split(':', 1)
             addr = (host, int(port))
             if len(addr) != 2:
                 return die('invalid address: %s' % http)
 
             httpd = mozhttpd.MozHttpd(host=addr[0], port=addr[1],