Python quickstart.generate函数代码示例

def test_quickstart_all_answers(tempdir):
    answers = {
        'Root path': tempdir,
        'Separate source and build': 'y',
        'Name prefix for templates': '.',
        'Project name': u'STASI™'.encode('utf-8'),
        'Author name': u'Wolfgang Schäuble & G\'Beckstein'.encode('utf-8'),
        'Project version': '2.0',
        'Project release': '2.0.1',
        'Source file suffix': '.txt',
        'Name of your master document': 'contents',
        'autodoc': 'y',
        'doctest': 'yes',
        'intersphinx': 'no',
        'todo': 'n',
        'coverage': 'no',
        'pngmath': 'N',
        'mathjax': 'no',
        'ifconfig': 'no',
        'viewcode': 'no',
        'Create Makefile': 'no',
        'Create Windows command file': 'no',
        'Do you want to use the epub builder': 'yes',
    }
    qs.term_input = mock_raw_input(answers, needanswer=True)
    qs.TERM_ENCODING = 'utf-8'
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    conffile = tempdir / 'source' / 'conf.py'
    assert conffile.isfile()
    ns = {}
    execfile_(conffile, ns)
    assert ns['extensions'] == ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
    assert ns['templates_path'] == ['.templates']
    assert ns['source_suffix'] == '.txt'
    assert ns['master_doc'] == 'contents'
    assert ns['project'] == u'STASI™'
    assert ns['copyright'] == u'%s, Wolfgang Schäuble & G\'Beckstein' % \
           time.strftime('%Y')
    assert ns['version'] == '2.0'
    assert ns['release'] == '2.0.1'
    assert ns['html_static_path'] == ['.static']
    assert ns['latex_documents'] == [
        ('contents', 'STASI.tex', u'STASI™ Documentation',
         u'Wolfgang Schäuble \\& G\'Beckstein', 'manual')]
    assert ns['epub_author'] == u'Wolfgang Schäuble & G\'Beckstein'
    assert ns['man_pages'] == [
        ('contents', 'stasi', u'STASI™ Documentation',
         [u'Wolfgang Schäuble & G\'Beckstein'], 1)]
    assert ns['texinfo_documents'] == [
        ('contents', 'STASI', u'STASI™ Documentation',
         u'Wolfgang Schäuble & G\'Beckstein', 'STASI',
         'One line description of project.', 'Miscellaneous'),]

    assert (tempdir / 'build').isdir()
    assert (tempdir / 'source' / '.static').isdir()
    assert (tempdir / 'source' / '.templates').isdir()
    assert (tempdir / 'source' / 'contents.txt').isfile()

def test_quickstart_defaults(tempdir):
    answers = {
        'Root path': tempdir,
        'Project name': 'Sphinx Test',
        'Author name': 'Georg Brandl',
        'Project version': '0.1',
    }
    qs.term_input = mock_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    conffile = tempdir / 'conf.py'
    assert conffile.isfile()
    ns = {}
    execfile_(conffile, ns)
    assert ns['extensions'] == []
    assert ns['templates_path'] == ['_templates']
    assert ns['source_suffix'] == '.rst'
    assert ns['master_doc'] == 'index'
    assert ns['project'] == 'Sphinx Test'
    assert ns['copyright'] == '%s, Georg Brandl' % time.strftime('%Y')
    assert ns['version'] == '0.1'
    assert ns['release'] == '0.1'
    assert ns['todo_include_todos'] is False
    assert ns['html_static_path'] == ['_static']
    assert ns['latex_documents'] == [
        ('index', 'SphinxTest.tex', 'Sphinx Test Documentation',
         'Georg Brandl', 'manual')]

    assert (tempdir / '_static').isdir()
    assert (tempdir / '_templates').isdir()
    assert (tempdir / 'index.rst').isfile()
    assert (tempdir / 'Makefile').isfile()
    assert (tempdir / 'make.bat').isfile()

    def sphinx(self):
        """
        Initialize Sphinx documentation for this project.


        Return: None
        Exceptions: None
        """
        try:
            from sphinx import quickstart
        except ImportError:
            print "Can't import Sphinx. Skipping"
            return

        sphinxopts = dict(dotfile.items("sphinx"))
        for f in sphinxopts:
            if sphinxopts[f] in ["False"]:
                sphinxopts[f] = False
            if sphinxopts[f] in ["True"]:
                sphinxopts[f] = True

        sphinxopts["path"] = self.root + "doc"
        sphinxopts["project"] = args.name
        if variable("author", None, ask="Project Author"):
            sphinxopts["author"] = variable("author", None)
        sphinxopts["version"] = self.version
        sphinxopts["release"] = self.version

        quickstart.ask_user(sphinxopts)
        quickstart.generate(sphinxopts)
        return

def createNewProject(path, project_name, author):
    d= {
        'path': path,
        'sep': True,
        'dot': '_',
        'project': project_name,
        'author': author,
        'version': '1.0',
        'release': '1.0',
        'suffix': '.rst',
        'master': 'index',
        'epub': False,
        'ext_autodoc': False,
        'ext_doctest': False,
        'ext_intersphinx': False,
        'ext_todo': False,
        'ext_coverage': False,
        'ext_pngmath': False,
        'ext_mathiax': False,
        'ext_ifconfig': True,
        'ext_todo': True,
        'ext_viewcode': False,
        'makefile': True,
        'batchfile': False,
    }
    generate(d)

def make_doc_directory(config, path):
    sphinx_conf = {
            'path'           : path,   # root path
            'sep'            : False,
            'dot'            : '_',
            'project'        : config['project_name'],
            'author'         : config['author'],
            'version'        : config['version'],
            'release'        : config['version'],
            'suffix'         : '.rst',
            'master'         : 'index',
            'epub'           : True,
            'ext_autodoc'    : True,
            'ext_doctest'    : False,
            'ext_interspinx' : True,
            'ext_todo'       : True,
            'ext_coverage'   : False,
            'ext_pngmath'    : True,
            'ext_mathjax'    : False,
            'ext_ifconfig'   : True,
            'ext_viewcode'   : True,
            'makefile'       : True,
            'batchfile'      : True}
    quickstart.generate(sphinx_conf)
    write_cmdline(config, os.path.join(path, 'cmdline.rst'))
    modify_doc_makefile(config, os.path.join(path, 'Makefile'))
    modify_doc_index(config, os.path.join(path, 'index.rst'))

def make_doc_directory(config, path):
    sphinx_conf = {
            'path'           : path,   # root path
            'sep'            : False,
            'dot'            : '_',
            'project'        : config['project_name'],
            'author'         : config['author'],
            'version'        : '@@[email protected]@',
            'release'        : '@@[email protected]@',
            'suffix'         : '.rst',
            'master'         : 'index',
            'epub'           : True,
            'ext_autodoc'    : True,
            'ext_doctest'    : False,
            'ext_interspinx' : True,
            'ext_todo'       : True,
            'ext_coverage'   : False,
            'ext_pngmath'    : True,
            'ext_mathjax'    : False,
            'ext_ifconfig'   : True,
            'ext_viewcode'   : True,
            'makefile'       : True,
            'batchfile'      : True}
    quickstart.generate(sphinx_conf)
    src_path = os.path.join(path, 'conf.py')
    with open(src_path, 'r') as src:
        with open(os.path.join(path, 'conf.py.skel'), 'w') as dst:
            for line in src.readlines():
                if RE_HTML_THEME.match(line):
                    line = 'html_theme = "openlmitheme"\n'
                dst.write(line)
    os.unlink(src_path)
    write_cmdline(config, os.path.join(path, 'cmdline.rst'))
    modify_doc_makefile(config, os.path.join(path, 'Makefile'))
    modify_doc_index(config, os.path.join(path, 'index.rst'))

def main(argv=sys.argv):
    """Parse and check the command line arguments."""
    parser = setup_parser()

    (opts, args) = parser.parse_args(argv[1:])

    if not args:
        parser.error('A package path is required.')

    rootpath, excludes = args[0], args[1:]
    if not opts.destdir:
        parser.error('An output directory is required.')
    if opts.header is None:
        opts.header = path.normpath(rootpath).split(path.sep)[-1]
    if opts.suffix.startswith('.'):
        opts.suffix = opts.suffix[1:]
    if not path.isdir(rootpath):
        print >>sys.stderr, '%s is not a directory.' % rootpath
        sys.exit(1)
    if not path.isdir(opts.destdir):
        if not opts.dryrun:
            os.makedirs(opts.destdir)
    rootpath = path.normpath(path.abspath(rootpath))
    excludes = normalize_excludes(rootpath, excludes)
    modules = recurse_tree(rootpath, excludes, opts)
    if opts.full:
        from sphinx import quickstart as qs
        modules.sort()
        prev_module = ''
        text = ''
        for module in modules:
            if module.startswith(prev_module + '.'):
                continue
            prev_module = module
            text += '   %s\n' % module
        d = dict(
            path = opts.destdir,
            sep  = False,
            dot  = '_',
            project = opts.header,
            author = opts.author or 'Author',
            version = opts.version or '',
            release = opts.release or opts.version or '',
            suffix = '.' + opts.suffix,
            master = 'index',
            epub = True,
            ext_autodoc = True,
            ext_viewcode = True,
            makefile = True,
            batchfile = True,
            mastertocmaxdepth = opts.maxdepth,
            mastertoctree = text,
        )
        if not opts.dryrun:
            qs.generate(d, silent=True, overwrite=opts.force)
    elif not opts.notoc:
        create_modules_toc_file(modules, opts)

def bootstrap(path, name, version, release=None):

    d = dict((
        # root path
        ("path", path),
        # separate source and build dirs (bool)
        ("sep", False),
        # name prefix for templates and static dir
        ("dot", ""),
        # project name
        ("project", name),
        # Author name(s)
        ("author", u"Lionel Dricot & Izidor Matušov"),
        # Project version, e.g. 2.5
        ("version", version or ""),
        # Project release, e.g. 2.5.1
        ("release", release or version or ""),
        # Source file suffix
        ("suffix", ".rst"),
        # master document name (without suffix)
        ("master", "index"),
        # Maximum depth of submodules to show in the TOC (int)
        ("mastertocmaxdepth", 4),
        # add configuration for epub builder
        ("epub", False),
        # automatically insert docstrings from modules (bool)
        ("ext_autodoc", True),
        # automatically test code in doctest blocks (bool)
        ("ext_doctest", False),
        # link Sphinx docs of different projects (bool)
        ("ext_intersphinx", False),
        # write "todo" entries (bool)
        ("ext_todo", True),
        # checks for documentation coverage (bool)
        ("ext_coverage", False),
        # include math, rendered as PNG images (bool)
        ("ext_pngmath", False),
        # include math, rendered in the browser by MathJax (bool)
        ("ext_mathjax", True),
        # conditional inclusion of content based on config values (bool)
        ("ext_ifconfig", False),
        # include links to the source code of documented Python objects (bool)
        ("ext_viewcode", True),
        # create Makefile (bool)
        ("makefile", False),
        # create Windows command file (bool)
        ("batchfile", False),
    ))

    if not isdir(path):
        os.makedirs(path)

    modules = recurse_tree(name, d)
    d["mastertoctree"] = create_modules_list(modules)
    create_modules_toc_file(modules, d)

    generate(d, silent=True, overwrite=True)

def test_generated_files_eol(tempdir):
    answers = {
        'Root path': tempdir,
        'Project name': 'Sphinx Test',
        'Author name': 'Georg Brandl',
        'Project version': '0.1',
    }
    qs.term_input = mock_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    def assert_eol(filename, eol):
        content = filename.bytes().decode('unicode-escape')
        assert all([l[-len(eol):] == eol for l in content.splitlines(True)])

    assert_eol(tempdir / 'make.bat', '\r\n')
    assert_eol(tempdir / 'Makefile', '\n')

def make_doc_directory(config, path):
    sphinx_conf = {
            'path'           : path,   # root path
            'sep'            : False,
            'dot'            : '_',
            'project'        : config['project_name'],
            'author'         : config['author'],
            'version'        : '@@[email protected]@',
            'release'        : '@@[email protected]@',
            'suffix'         : '.rst',
            'master'         : 'index',
            'epub'           : True,
            'ext_autodoc'    : True,
            'ext_doctest'    : False,
            'ext_interspinx' : True,
            'ext_todo'       : True,
            'ext_coverage'   : False,
            'ext_pngmath'    : True,
            'ext_mathjax'    : False,
            'ext_ifconfig'   : True,
            'ext_viewcode'   : True,
            'makefile'       : True,
            'batchfile'      : True}
    quickstart.generate(sphinx_conf)
    src_path = os.path.join(path, 'conf.py')
    with open(src_path, 'r') as src:
        with open(os.path.join(path, 'conf.py.skel'), 'w') as dst:
            for line in src.readlines():
                if RE_HTML_THEME.match(line):
                    line = 'html_theme = "openlmitheme"\n'
                dst.write(line)
    os.unlink(src_path)
    write_cmdline(config, os.path.join(path, 'cmdline.rst'))
    modify_doc_makefile(config, os.path.join(path, 'Makefile'))
    modify_doc_index(config, os.path.join(path, 'index.rst'))
    with open(os.path.join(path, 'python.rst'), 'w') as dst:
        name = str(config['command']).capitalize()
        match = RE_PROJECT_NAME.match(config['project_name'])
        if match:
            name = match.group(1)
        title = "%s Script python reference" % name
        heading = "%s\n%s" % (title, '='*len(title))
        dst.write(DOC_PYTHON_REFERENCE.format(
            name=config['command'], heading=heading))

def test_default_filename(tempdir):
    answers = {
        'Root path': tempdir,
        'Project name': u'\u30c9\u30a4\u30c4',  # Fullwidth characters only
        'Author name': 'Georg Brandl',
        'Project version': '0.1',
    }
    qs.term_input = mock_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    conffile = tempdir / 'conf.py'
    assert conffile.isfile()
    ns = {}
    execfile_(conffile, ns)
    assert ns['latex_documents'][0][1] == 'sphinx.tex'
    assert ns['man_pages'][0][1] == 'sphinx'
    assert ns['texinfo_documents'][0][1] == 'sphinx'

def test_quickstart_defaults(tempdir):
    answers = {
        'Root path': tempdir,
        'Project name': 'Sphinx Test',
        'Author name': 'Georg Brandl',
        'Project version': '0.1',
    }
    qs.term_input = mock_raw_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    conffile = tempdir / 'conf.py'
    assert conffile.isfile()
    ns = {}
    f = open(conffile, 'rbU')
    try:
        code = compile(f.read(), conffile, 'exec')
    finally:
        f.close()
    exec code in ns
    assert ns['extensions'] == []
    assert ns['templates_path'] == ['_templates']
    assert ns['source_suffix'] == '.rst'
    assert ns['master_doc'] == 'index'
    assert ns['project'] == 'Sphinx Test'
    assert ns['copyright'] == '%s, Georg Brandl' % time.strftime('%Y')
    assert ns['version'] == '0.1'
    assert ns['release'] == '0.1'
    assert ns['html_static_path'] == ['_static']
    assert ns['latex_documents'] == [
        ('index', 'SphinxTest.tex', 'Sphinx Test Documentation',
         'Georg Brandl', 'manual')]

    assert (tempdir / '_static').isdir()
    assert (tempdir / '_templates').isdir()
    assert (tempdir / 'index.rst').isfile()
    assert (tempdir / 'Makefile').isfile()
    assert (tempdir / 'make.bat').isfile()

def test_quickstart_and_build(tempdir):
    answers = {
        'Root path': tempdir,
        'Project name': u'Fullwidth characters: \u30c9\u30a4\u30c4',
        'Author name': 'Georg Brandl',
        'Project version': '0.1',
    }
    qs.term_input = mock_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    app = application.Sphinx(
        tempdir,  # srcdir
        tempdir,  # confdir
        (tempdir / '_build' / 'html'),  # outdir
        (tempdir / '_build' / '.doctree'),  # doctreedir
        'html',  # buildername
        status=StringIO(),
        warning=warnfile)
    app.builder.build_all()
    warnings = warnfile.getvalue()
    assert not warnings

def test_quickstart_defaults(tempdir):
    answers = {
        "Root path": tempdir,
        "Project name": "Sphinx Test",
        "Author name": "Georg Brandl",
        "Project version": "0.1",
    }
    qs.term_input = mock_raw_input(answers)
    d = {}
    qs.ask_user(d)
    qs.generate(d)

    conffile = tempdir / "conf.py"
    assert conffile.isfile()
    ns = {}
    f = open(conffile, "U")
    try:
        code = compile(f.read(), conffile, "exec")
    finally:
        f.close()
    exec code in ns
    assert ns["extensions"] == []
    assert ns["templates_path"] == ["_templates"]
    assert ns["source_suffix"] == ".rst"
    assert ns["master_doc"] == "index"
    assert ns["project"] == "Sphinx Test"
    assert ns["copyright"] == "%s, Georg Brandl" % time.strftime("%Y")
    assert ns["version"] == "0.1"
    assert ns["release"] == "0.1"
    assert ns["html_static_path"] == ["_static"]
    assert ns["latex_documents"] == [("index", "SphinxTest.tex", "Sphinx Test Documentation", "Georg Brandl", "manual")]

    assert (tempdir / "_static").isdir()
    assert (tempdir / "_templates").isdir()
    assert (tempdir / "index.rst").isfile()
    assert (tempdir / "Makefile").isfile()
    assert (tempdir / "make.bat").isfile()

    def create_new(self, silent=True):
        """
        Calls sphinx.quickstart to populate a new project directory.

        Uses the currently-configured options in self.conf_dict and
        self.quickstart_params.
        """

        defaults = quickstart_defaults.copy()

        defaults['path'] = self.dirname
        defaults.update(self.quickstart_params)

        quickstart.generate(defaults, silent=silent)

        if defaults['sep']:
            self.source_dir = os.path.join(self.dirname, 'source')
        else:
            self.source_dir = self.dirname
        self.build_dir = os.path.join(
            self.dirname, '%sbuild' % defaults['dot'])
        if self.conf_dict is not None:
            self.conf_fn = os.path.join(self.source_dir, 'conf.py')
            helpers.update_conf(self.conf_fn, self.conf_dict)