def build_docs( self, path=None, fmt="html", outdir=None, auto_open=True, serve=True, http=None, archive=False, upload=False, jobs=None, write_url=None, verbose=None, ): if self.check_jsdoc(): return die(JSDOC_NOT_FOUND) self.activate_virtualenv() self.virtualenv_manager.install_pip_requirements( os.path.join(here, "requirements.txt")) import webbrowser from livereload import Server from moztreedocs.package import create_tarball unique_id = str(uuid.uuid1()) outdir = outdir or os.path.join(self.topobjdir, "docs") savedir = os.path.join(outdir, fmt) path = path or self.topsrcdir path = os.path.normpath(os.path.abspath(path)) docdir = self._find_doc_dir(path) if not docdir: print(self._dump_sphinx_backtrace()) return die("failed to generate documentation:\n" "%s: could not find docs at this location" % path) result = self._run_sphinx(docdir, savedir, fmt=fmt, jobs=jobs, verbose=verbose) if result != 0: print(self._dump_sphinx_backtrace()) return die("failed to generate documentation:\n" "%s: sphinx return code %d" % (path, result)) else: print("\nGenerated documentation:\n%s" % savedir) print("Post processing HTML files") self._post_process_html(savedir) # Upload the artifact containing the link to S3 # This would be used by code-review to post the link to Phabricator if write_url is not None: base_link = ( "http://gecko-docs.mozilla.org-l1.s3-website.us-west-2.amazonaws.com/" ) unique_link = base_link + unique_id + "/index.html" with open(write_url, "w") as fp: fp.write(unique_link) fp.flush() if archive: archive_path = os.path.join(outdir, "%s.tar.gz" % self.project) create_tarball(archive_path, savedir) print("Archived to %s" % archive_path) if upload: self._s3_upload(savedir, self.project, unique_id, self.version) if not serve: index_path = os.path.join(savedir, "index.html") if auto_open and os.path.isfile(index_path): webbrowser.open(index_path) return # Create livereload server. Any files modified in the specified docdir # will cause a re-build and refresh of the browser (if open). try: host, port = http.split(":", 1) port = int(port) except ValueError: return die("invalid address: %s" % http) server = Server() sphinx_trees = self.manager.trees or {savedir: docdir} for _, src in sphinx_trees.items(): run_sphinx = partial(self._run_sphinx, src, savedir, fmt=fmt, jobs=jobs, verbose=verbose) server.watch(src, run_sphinx) server.serve( host=host, port=port, root=savedir, open_url_delay=0.1 if auto_open else None, )
def build_docs( self, path=None, fmt="html", outdir=None, auto_open=True, serve=True, http=None, archive=False, upload=False, jobs=None, write_url=None, verbose=None, ): # TODO: Bug 1704891 - move the ESLint setup tools to a shared place. sys.path.append(mozpath.join(self.topsrcdir, "tools", "lint", "eslint")) import setup_helper setup_helper.set_project_root(self.topsrcdir) if not setup_helper.check_node_executables_valid(): return 1 setup_helper.eslint_maybe_setup() # Set the path so that Sphinx can find jsdoc, unfortunately there isn't # a way to pass this to Sphinx itself at the moment. os.environ["PATH"] = ( mozpath.join(self.topsrcdir, "node_modules", ".bin") + os.pathsep + self._node_path() + os.pathsep + os.environ["PATH"]) self.activate_virtualenv() self.virtualenv_manager.install_pip_requirements( os.path.join(here, "requirements.txt")) import webbrowser from livereload import Server from moztreedocs.package import create_tarball unique_id = "%s/%s" % (self.project, str(uuid.uuid1())) outdir = outdir or os.path.join(self.topobjdir, "docs") savedir = os.path.join(outdir, fmt) path = path or self.topsrcdir path = os.path.normpath(os.path.abspath(path)) docdir = self._find_doc_dir(path) if not docdir: print(self._dump_sphinx_backtrace()) return die("failed to generate documentation:\n" "%s: could not find docs at this location" % path) result = self._run_sphinx(docdir, savedir, fmt=fmt, jobs=jobs, verbose=verbose) if result != 0: print(self._dump_sphinx_backtrace()) return die("failed to generate documentation:\n" "%s: sphinx return code %d" % (path, result)) else: print("\nGenerated documentation:\n%s" % savedir) # Upload the artifact containing the link to S3 # This would be used by code-review to post the link to Phabricator if write_url is not None: unique_link = BASE_LINK + unique_id + "/index.html" with open(write_url, "w") as fp: fp.write(unique_link) fp.flush() print("Generated " + write_url) if archive: archive_path = os.path.join(outdir, "%s.tar.gz" % self.project) create_tarball(archive_path, savedir) print("Archived to %s" % archive_path) if upload: self._s3_upload(savedir, self.project, unique_id, self.version) if not serve: index_path = os.path.join(savedir, "index.html") if auto_open and os.path.isfile(index_path): webbrowser.open(index_path) return # Create livereload server. Any files modified in the specified docdir # will cause a re-build and refresh of the browser (if open). try: host, port = http.split(":", 1) port = int(port) except ValueError: return die("invalid address: %s" % http) server = Server() sphinx_trees = self.manager.trees or {savedir: docdir} for _, src in sphinx_trees.items(): run_sphinx = partial(self._run_sphinx, src, savedir, fmt=fmt, jobs=jobs, verbose=verbose) server.watch(src, run_sphinx) server.serve( host=host, port=port, root=savedir, open_url_delay=0.1 if auto_open else None, )
def build_docs(self, path=None, fmt='html', outdir=None, auto_open=True, serve=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_pipenv(os.path.join(here, 'Pipfile')) import webbrowser from livereload import Server from moztreedocs.package import create_tarball outdir = outdir or os.path.join(self.topobjdir, 'docs') savedir = os.path.join(outdir, fmt) path = path or os.path.join(self.topsrcdir, 'tools') path = os.path.normpath(os.path.abspath(path)) 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) result = self._run_sphinx(docdir, savedir, fmt=fmt) 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' % self.project) create_tarball(archive_path, savedir) print('Archived to %s' % archive_path) if upload: self._s3_upload(savedir, self.project, self.version) if not serve: index_path = os.path.join(savedir, 'index.html') if auto_open and os.path.isfile(index_path): webbrowser.open(index_path) return # Create livereload server. Any files modified in the specified docdir # will cause a re-build and refresh of the browser (if open). try: host, port = http.split(':', 1) port = int(port) except ValueError: return die('invalid address: %s' % http) server = Server() sphinx_trees = self.manager.trees or {savedir: docdir} for dest, src in sphinx_trees.items(): run_sphinx = partial(self._run_sphinx, src, savedir, fmt=fmt) server.watch(src, run_sphinx) server.serve(host=host, port=port, root=savedir, open_url_delay=0.1 if auto_open else None)