tools/docs/moztreedocs/__init__.py@6474c204b198 (annotated)
tools/docs/moztreedocs/__init__.py
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | # This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 2 | # License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 3 | # file, # You can obtain one at http://mozilla.org/MPL/2.0/. |
| michael@0 | 4 | |
| michael@0 | 5 | from __future__ import unicode_literals |
| michael@0 | 6 | |
| michael@0 | 7 | import os |
| michael@0 | 8 | |
| michael@0 | 9 | from mozpack.copier import FileCopier |
| michael@0 | 10 | from mozpack.files import FileFinder |
| michael@0 | 11 | from mozpack.manifests import InstallManifest |
| michael@0 | 12 | |
| michael@0 | 13 | import sphinx |
| michael@0 | 14 | import sphinx.apidoc |
| michael@0 | 15 | |
| michael@0 | 16 | |
| michael@0 | 17 | class SphinxManager(object): |
| michael@0 | 18 | """Manages the generation of Sphinx documentation for the tree.""" |
| michael@0 | 19 | |
| michael@0 | 20 | def __init__(self, topsrcdir, main_path, output_dir): |
| michael@0 | 21 | self._topsrcdir = topsrcdir |
| michael@0 | 22 | self._output_dir = output_dir |
| michael@0 | 23 | self._conf_py_path = os.path.join(main_path, 'conf.py') |
| michael@0 | 24 | self._index_path = os.path.join(main_path, 'index.rst') |
| michael@0 | 25 | self._trees = {} |
| michael@0 | 26 | self._python_package_dirs = set() |
| michael@0 | 27 | |
| michael@0 | 28 | def add_tree(self, source_dir, dest_dir): |
| michael@0 | 29 | """Add a directory from where docs should be sourced.""" |
| michael@0 | 30 | if dest_dir in self._trees: |
| michael@0 | 31 | raise Exception('%s has already been registered as a destination.' |
| michael@0 | 32 | % dest_dir) |
| michael@0 | 33 | |
| michael@0 | 34 | self._trees[dest_dir] = source_dir |
| michael@0 | 35 | |
| michael@0 | 36 | def add_python_package_dir(self, source_dir): |
| michael@0 | 37 | """Add a directory containing Python packages. |
| michael@0 | 38 | |
| michael@0 | 39 | Added directories will have Python API docs generated automatically. |
| michael@0 | 40 | """ |
| michael@0 | 41 | self._python_package_dirs.add(source_dir) |
| michael@0 | 42 | |
| michael@0 | 43 | def generate_docs(self, fmt): |
| michael@0 | 44 | """Generate documentation using Sphinx.""" |
| michael@0 | 45 | self._synchronize_docs() |
| michael@0 | 46 | self._generate_python_api_docs() |
| michael@0 | 47 | |
| michael@0 | 48 | old_env = os.environ.copy() |
| michael@0 | 49 | try: |
| michael@0 | 50 | os.environ['MOZILLA_DIR'] = self._topsrcdir |
| michael@0 | 51 | args = [ |
| michael@0 | 52 | 'sphinx', |
| michael@0 | 53 | '-b', fmt, |
| michael@0 | 54 | os.path.join(self._output_dir, 'staging'), |
| michael@0 | 55 | os.path.join(self._output_dir, fmt), |
| michael@0 | 56 | ] |
| michael@0 | 57 | |
| michael@0 | 58 | return sphinx.main(args) |
| michael@0 | 59 | finally: |
| michael@0 | 60 | os.environ.clear() |
| michael@0 | 61 | os.environ.update(old_env) |
| michael@0 | 62 | |
| michael@0 | 63 | def _generate_python_api_docs(self): |
| michael@0 | 64 | """Generate Python API doc files.""" |
| michael@0 | 65 | out_dir = os.path.join(self._output_dir, 'staging', 'python') |
| michael@0 | 66 | base_args = ['sphinx', '--no-toc', '-o', out_dir] |
| michael@0 | 67 | |
| michael@0 | 68 | for p in sorted(self._python_package_dirs): |
| michael@0 | 69 | full = os.path.join(self._topsrcdir, p) |
| michael@0 | 70 | |
| michael@0 | 71 | finder = FileFinder(full, find_executables=False) |
| michael@0 | 72 | dirs = {os.path.dirname(f[0]) for f in finder.find('**')} |
| michael@0 | 73 | |
| michael@0 | 74 | excludes = {d for d in dirs if d.endswith('test')} |
| michael@0 | 75 | |
| michael@0 | 76 | args = list(base_args) |
| michael@0 | 77 | args.append(full) |
| michael@0 | 78 | args.extend(excludes) |
| michael@0 | 79 | |
| michael@0 | 80 | sphinx.apidoc.main(args) |
| michael@0 | 81 | |
| michael@0 | 82 | def _synchronize_docs(self): |
| michael@0 | 83 | m = InstallManifest() |
| michael@0 | 84 | |
| michael@0 | 85 | m.add_symlink(self._conf_py_path, 'conf.py') |
| michael@0 | 86 | |
| michael@0 | 87 | for dest, source in sorted(self._trees.items()): |
| michael@0 | 88 | source_dir = os.path.join(self._topsrcdir, source) |
| michael@0 | 89 | for root, dirs, files in os.walk(source_dir): |
| michael@0 | 90 | for f in files: |
| michael@0 | 91 | source_path = os.path.join(root, f) |
| michael@0 | 92 | rel_source = source_path[len(source_dir) + 1:] |
| michael@0 | 93 | |
| michael@0 | 94 | m.add_symlink(source_path, os.path.join(dest, rel_source)) |
| michael@0 | 95 | |
| michael@0 | 96 | stage_dir = os.path.join(self._output_dir, 'staging') |
| michael@0 | 97 | copier = FileCopier() |
| michael@0 | 98 | m.populate_registry(copier) |
| michael@0 | 99 | copier.copy(stage_dir) |
| michael@0 | 100 | |
| michael@0 | 101 | with open(self._index_path, 'rb') as fh: |
| michael@0 | 102 | data = fh.read() |
| michael@0 | 103 | |
| michael@0 | 104 | indexes = ['%s/index' % p for p in sorted(self._trees.keys())] |
| michael@0 | 105 | indexes = '\n '.join(indexes) |
| michael@0 | 106 | |
| michael@0 | 107 | packages = [os.path.basename(p) for p in self._python_package_dirs] |
| michael@0 | 108 | packages = ['python/%s' % p for p in packages] |
| michael@0 | 109 | packages = '\n '.join(sorted(packages)) |
| michael@0 | 110 | data = data.format(indexes=indexes, python_packages=packages) |
| michael@0 | 111 | |
| michael@0 | 112 | with open(os.path.join(stage_dir, 'index.rst'), 'wb') as fh: |
| michael@0 | 113 | fh.write(data) |
