corysanin/tubestation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time r=mshal

Browse Source 
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
This commit is contained in:
Andrew Halberstadt
2018-04-06 10:30:31 -04:00
parent a7822f165d
commit bb9120f412
1 changed files with 34 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
tools/docs/mach_commands.py
View File

@@ -27,8 +27,8 @@ class Documentation(MachCommandBase):
@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',
@@ -43,7 +43,7 @@ class Documentation(MachCommandBase):
'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')
@@ -58,57 +58,45 @@ class Documentation(MachCommandBase):
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 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 upload:
self._s3_upload(savedir, props['project'], props['version'])
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 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)