Python sphinx.main函数代码示例

    def intl_update(self):
        ui.info(ui.blue, "::", ui.reset, "Generating message catalogs ...")
        import sphinx
        from sphinx_intl.commands import run as sphinx_intl_run
        # First step: run sphinx-build -b gettext
        cmd = [sys.executable, "-c", self.build_dir, "-b", "gettext"]
        cmd.append(self.source_dir)
        locale_dir = os.path.join(self.source_dir, "locale")
        cmd.append(locale_dir)
        rc = 0
        try:
            sphinx.main(argv=cmd)
        except SystemExit as e:
            rc = e.code
        if rc != 0:
            raise SphinxBuildError(self)

        ui.info()

        # Second step: run sphinx-intl update -l <lingua> for every lingua
        ui.info(ui.blue, "::", ui.reset, "Updating .po files ...")
        for i, lingua in enumerate(self.linguas):
            ui.info_count(i, len(self.linguas), ui.blue, lingua)
            cmd = ["update",
                "-c", os.path.join(self.build_dir, "conf.py"),
                "--pot-dir", locale_dir,
                "--locale-dir", locale_dir,
                "--language", lingua]
            sphinx_intl_run(cmd)

def build_docs():
    """Build the Blogofile sphinx based documentation"""
    #Abort if sphinx isn't installed
    try:
        import sphinx
    except ImportError:
        return
    #print "Building the docs..."
    #Configure the theme
    #Insert the rendered head, headers, and footers into the theme
    config = sys.modules[globals()['__name__']]
    from mako.template import Template
    head_t = Template(open(os.path.join("_templates","head.mako")).read())
    head = head_t.render(**{'bf':bf})
    header_t = Template(open(os.path.join("_templates","header.mako")).read())
    header = header_t.render(**{'bf':bf})
    footer_t = Template(open(os.path.join("_templates","footer.mako")).read())
    footer = footer_t.render(**{'bf':bf})

    #Create the new layout.html from preparse_layout.html
    #Insert the rendered templates appropriately
    layout = open(os.path.join("_documentation","themes","blogofile",
                               "preparse_layout.html")).read()
    layout = layout.replace("blogofile_head_goes_here",head)
    layout = layout.replace("blogofile_header_goes_here",header)
    layout = layout.replace("blogofile_footer_goes_here",footer)
    layout_f = open(os.path.join("_documentation","themes","blogofile",
                               "layout.html"),"w")
    layout_f.write(layout)
    layout_f.close()
    logger.info("Compiling HTML Documentation..")
    sphinx.main(shlex.split("sphinx-build -q -b html _documentation "+
                            os.path.join("_site","documentation")))

def _plugin_build_docs(destdir, cfg, src="src"):
    """Builds the Sphinx docs for the plugin distribution, assuming it has
    a structure like the one created by plugin quickstart.
    """
    name = cfg.get("metadata", "name")
    version = cfg.get("metadata", "version")

    docdir = os.path.join(destdir, "docs")
    srcdir = os.path.abspath(os.path.join(destdir, src))

    sphinx.main(
        argv=[
            "",
            "-E",
            "-a",
            "-b",
            "html",
            "-Dversion=%s" % version,
            "-Drelease=%s" % version,
            "-d",
            os.path.join(srcdir, name, "sphinx_build", "doctrees"),
            docdir,
            os.path.join(srcdir, name, "sphinx_build", "html"),
        ]
    )

def _plugin_build_docs(destdir, cfg):
    """Builds the Sphinx docs for the plugin distribution, assuming it has
    a structure like the one created by plugin quickstart.
    """
    name = cfg.get('metadata', 'name')
    version = cfg.get('metadata', 'version')
    
    path_added = False
    try:
        docdir = os.path.join(destdir, 'docs')
        srcdir = os.path.join(destdir, 'src')
        
        # have to add srcdir to sys.path or autodoc won't find source code
        if srcdir not in sys.path:
            sys.path[0:0] = [srcdir]
            path_added = True
            
        sphinx.main(argv=['', '-E', '-a', '-b', 'html',
                          '-Dversion=%s' % version,
                          '-Drelease=%s' % version,
                          '-d', os.path.join(srcdir, name, 'sphinx_build', 'doctrees'), 
                          docdir, 
                          os.path.join(srcdir, name, 'sphinx_build', 'html')])
    finally:
        if path_added:
            sys.path.remove(srcdir)

    def run(self):
        if self.clean:
            if not os.path.exists(self.builddir):
                print('Nothing to clean, quiting...')
                return

            prompt = ('This action will remove all files in {0}, '
                      'would you like to continue? (y/N)').format(
                os.path.abspath(self.builddir))

            try:
                answer = raw_input(prompt)
            except NameError:
                answer = input(prompt)
            finally:
                if answer.lower() == 'y':
                    shutil.rmtree(self.builddir)
                else:
                    print('Operation aborted.')
        else:
            import sphinx

            sphinxbuild = os.environ.get('SPHINXBUILD', self.sphinxbuild)
            sphinxopts = os.environ.get('SPHINXOPTS', self.sphinxopts)
            args = '{0} -b {1} -d {2}/doctree {3} {4} {2}/{1}'

            self._process_images()
            for fmt in self.formats:
                sphinx.main(args.format(sphinxbuild,
                    fmt, self.builddir, sphinxopts, self.sourcedir).split())

def build_docs(parser=None, options=None, args=None):
    """A script (openmdao build_docs) points to this.  It generates the Sphinx
    documentation for openmdao.
    """
    global _is_release
    if args and parser:
        print_sub_help(parser, 'build_docs')
        return -1

    if options is not None and hasattr(options, 'version') and options.version:
        version = options.version
        shtitle = 'OpenMDAO Documentation v%s' % version
        _is_release = True
    else:
        _is_release = False
        try:
            tag, ncommits, commit = get_rev_info()
            version = "%s-%s-%s" % (tag, ncommits, commit)
            shtitle = 'OpenMDAO Documentation (%s commits after version %s)' % (ncommits, tag)
        except:
            # try to get commit id
            try:
                top = get_ancestor_dir(sys.executable, 3)
                if '-OpenMDAO-Framework-' in top:
                    commit = top.split('-')[-1]
                    version = "dev - commit id: %s" % commit
                    shtitle = "OpenMDAO Documentation (commit id %s)" % commit
                else:
                    raise RuntimeError("can't find commit id")
            except:
                version = "?-?-?"
                shtitle = "OpenMDAO Documentation (unknown revision)"

    branchdir, docdir, bindir = _get_dirnames()

    startdir = os.getcwd()
    if not os.path.isdir(docdir):
        raise RuntimeError('doc directory '+docdir+' not found')

    _write_src_docs(branchdir, docdir)
    _make_license_table(docdir)

    os.chdir(docdir)
    try:
        # make necessary directories
        if os.path.isdir(os.path.join('_build', 'html')):
            shutil.rmtree(os.path.join('_build', 'html'), onerror=onerror)
        if os.path.isdir(os.path.join('_build', 'doctrees')):
            shutil.rmtree(os.path.join('_build', 'doctrees'), onerror=onerror)
        os.makedirs(os.path.join('_build', 'html'))
        os.makedirs(os.path.join('_build', 'doctrees'))

        sphinx.main(argv=['-P', '-b', 'html',
                          '-Dhtml_short_title=%s' % shtitle,
                          '-Dversion=%s' % version,
                          '-Drelease=%s' % version,
                          '-d', os.path.join(docdir, '_build', 'doctrees'),
                          docdir, os.path.join(docdir, '_build', 'html')])
    finally:
        os.chdir(startdir)

    def run(self):
        try:
            import sphinx
        except ImportError:
            log.info('Sphinx not installed -- skipping documentation. (%s)', sys.exc_info()[1])
            return

        if not os.path.exists(self.out_dir):
            if self.dry_run:
                self.announce('skipping creation of directory %s (dry run)' % self.out_dir)
            else:
                self.announce('creating directory %s' % self.out_dir)
                os.makedirs(self.out_dir)
        if self.dry_run:
            self.announce('skipping %s (dry run)' % ' '.join(self.sphinx_args))
        else:
            self.announce('running %s' % ' '.join(self.sphinx_args))
            opath = sys.path
            try:
                # We need to point Sphinx at the built library, including
                # the extension module so that autodoc works properly.
                sys.path.insert(0,os.path.realpath(self.build_lib))
                sphinx.main(self.sphinx_args)
            finally:
                sys.path = opath;

    def main(self, format):
        '''Create the documentation. 
        '''
        if format not in FORMATS:
            raise Exception, 'bad format'

        self.writeModuleReference()    
        self.writeGeneratedChapters()    
        self.writeContents()    

        if format == 'html':
            dirOut = self.dirBuildHtml
            pathLaunch = os.path.join(self.dirBuildHtml, 'contents.html')
        elif format == 'latex':
            dirOut = self.dirBuildLatex
            #pathLaunch = os.path.join(dirBuildHtml, 'contents.html')
        elif format == 'pdf':
            dirOut = self.dirBuildPdf
        else:
            raise Exception('undefined format %s' % format)

        if common.getPlatform() in ['darwin', 'nix', 'win']:
            # -b selects the builder
            import sphinx
            sphinxList = ['sphinx', '-E', '-b', format, '-d', self.dirBuildDoctrees,
                         self.dirRst, dirOut] 
            sphinx.main(sphinxList)
    
        if format == 'html':
            webbrowser.open(pathLaunch)

    def DoTask(self):
        tmpDir = join(self.buildSetup.tmpDir, "chm")
        Prepare()
        #warnings.simplefilter('ignore', DeprecationWarning)
        sphinx.main([
            None,
            #"-a",
            "-b", "htmlhelp",
            "-E",
            "-P",
            "-D", "release=%s" % eg.Version.base,
            "-D", "templates_path=[]",
            "-d", EncodePath(join(self.buildSetup.tmpDir, ".doctree")),
            EncodePath(DOCS_SOURCE_DIR),
            tmpDir,
        ])

        print "calling HTML Help Workshop compiler"
        htmlHelpCompilerPath = GetHtmlHelpCompilerPath()
        if htmlHelpCompilerPath is None:
            raise Exception(
                "HTML Help Workshop command line compiler not found"
            )
        hhpPath = join(tmpDir, "EventGhost.hhp")
        StartProcess(htmlHelpCompilerPath, hhpPath)
        shutil.copy(join(tmpDir, "EventGhost.chm"), self.buildSetup.sourceDir)

    def run(self):
        # metadata contains information supplied in setup()
        metadata = self.distribution.metadata
        src_dir = (self.distribution.package_dir or {"": ""})[""]
        src_dir = os.path.join(os.getcwd(), src_dir)

        # Build docs from docstrings in *.py files
        sphinx.apidoc.main(["", "-e", "-o", os.path.join("docs", "source", "api"), src_dir])

        # Build the doc sources
        sphinx.main(
            [
                "",
                "-c",
                "docs",
                "-D",
                "project=" + metadata.name,
                "-D",
                "version=" + metadata.version,
                "-D",
                "release=" + metadata.version,
                os.path.join("docs", "source"),
                os.path.join("docs", "build"),
            ]
        )

def build_docs(srcdir, destdir, confdir = None, page = None):
    current_dir = os.getcwd()
    os.chdir(srcdir)

    _build_destdir = destdir
    args = ['sphinx-build',                          # Fake argv[0]
            '-b', 'html',                            # Use the JSON builder
            '-q',                                    # Do not output anything on standard output, only write warnings and errors to standard error. 
            srcdir,                                  # Source file directory
            _build_destdir,                          # Destination directory
            ]
    
    if confdir:
        args.insert(1, confdir)
        args.insert(1, '-c')
    
    if page:
        args.append(os.path.join(srcdir, page.path))
    else:
        if os.path.exists(destdir):
            shutil.rmtree(destdir)
        if not os.path.exists(_build_destdir):
            os.makedirs(_build_destdir)
            
    import sphinx
    sphinx.main(args)
    os.chdir(current_dir)

    def build_html_doc(self):
        """Build the html documentation."""
        try:
            import sphinx
        except ImportError:
            self.warn("sphinx not found, documentation won't be build.")
            return

        sphinx_ver = sphinx.__version__
        def digits(x):
            res = re.match('\d+', x)
            if res is None:
                return 0
            else:
                return int(res.group())
        if map(digits, sphinx_ver.split('.')) < [0, 5, 1]:
            self.warn("Sphinx's version is too old (%s, expected at least "
                    "0.5.1, documentation won't be build." % sphinx_ver)
            return

        # Build the documentation just like it is done through the Makefile
        sphinx.main([__file__,
            "-b", "html",
            "-d", os.path.join(BASE_DOCS_DIR, 'doctrees'),
            os.path.join(BASE_DOCS_DIR, 'src'), DOCS_DIR])

    def run(self):
        # We import here to ensure that setup.py has had a chance to install the
        # relevant package eggs first.
        import sphinx
        import sphinx.apidoc

        metadata = self.distribution.metadata
        src_dir = os.path.join(PYTHON_STEM, self.distribution.package_dir[""], "grpc")
        sys.path.append(src_dir)
        sphinx.apidoc.main(
            [
                "",
                "--force",
                "--full",
                "-H",
                metadata.name,
                "-A",
                metadata.author,
                "-V",
                metadata.version,
                "-R",
                metadata.version,
                "-o",
                os.path.join("doc", "src"),
                src_dir,
            ]
        )
        conf_filepath = os.path.join("doc", "src", "conf.py")
        with open(conf_filepath, "a") as conf_file:
            conf_file.write(CONF_PY_ADDENDUM)
        sphinx.main(["", os.path.join("doc", "src"), os.path.join("doc", "build")])

    def build(self, expected_return=0):
        print("")

        with mock.patch.object(sys, "exit") as mock_exit:
            sys.argv = ["sphinx-build", "-q", "-d", paths.doctree, "-b", "html", paths.root, paths.html]
            sphinx.main(sys.argv)
            mock_exit.assert_called_once_with(expected_return)

 def call_sphinx(builder, workdir, extraopts=None):
     import sphinx
     if extraopts is None:
         extraopts = []
     if not options['--cache']:
         extraopts.append('-E')
     sphinx.main(['', '-b', builder] + extraopts +
                 [os.path.join(throot, 'doc'), workdir])