Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time draft
authorAndrew Halberstadt <ahalberstadt@mozilla.com>
Fri, 06 Apr 2018 10:30:31 -0400
changeset 783640 76437a58b4c919c953fcb7680fb126585fe94795
parent 783610 be49359d01dd917615ec25d0062b4fb1eeacb599
child 783641 cb65559b2a01f7b73955f38cfe809f73db39fe0a
push id106750
push userahalberstadt@mozilla.com
push dateTue, 17 Apr 2018 15:22:13 +0000
bugs1410424
milestone61.0a1
Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time 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],