diff options
Diffstat (limited to 'sphinx/quickstart.py')
| -rw-r--r-- | sphinx/quickstart.py | 267 |
1 files changed, 215 insertions, 52 deletions
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 173f26a1..cfdb97e7 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -15,8 +15,9 @@ from os import path TERM_ENCODING = getattr(sys.stdin, 'encoding', None) from sphinx.util import make_filename -from sphinx.util.console import purple, bold, red, turquoise, nocolor, color_terminal -from sphinx.util.texescape import tex_escape_map +from sphinx.util.console import purple, bold, red, turquoise, \ + nocolor, color_terminal +from sphinx.util import texescape PROMPT_PREFIX = '> ' @@ -29,9 +30,6 @@ QUICKSTART_CONF = '''\ # # This file is execfile()d with the current directory set to its containing dir. # -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# # Note that not all possible configuration values are present in this # autogenerated file. # @@ -40,13 +38,12 @@ QUICKSTART_CONF = '''\ import sys, os -# If your extensions (or modules documented by autodoc) are in another directory, +# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.append(os.path.abspath('.')) -# General configuration -# --------------------- +# -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -111,14 +108,23 @@ exclude_trees = [%(exclude_trees)s] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- -# Options for HTML output -# ----------------------- +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'default.css' +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". @@ -165,8 +171,8 @@ html_static_path = ['%(dot)sstatic'] # If true, the index is split into individual pages for each letter. #html_split_index = False -# If true, the reST sources are included in the HTML build as _sources/<name>. -#html_copy_source = True +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the @@ -180,8 +186,7 @@ html_static_path = ['%(dot)sstatic'] htmlhelp_basename = '%(project_fn)sdoc' -# Options for LaTeX output -# ------------------------ +# -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -190,7 +195,7 @@ htmlhelp_basename = '%(project_fn)sdoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('%(master)s', '%(project_fn)s.tex', ur'%(project_doc_texescaped)s', ur'%(author_texescaped)s', 'manual'), @@ -217,11 +222,12 @@ latex_documents = [ INTERSPHINX_CONFIG = ''' # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/dev': None} +intersphinx_mapping = {'http://docs.python.org/': None} ''' MASTER_FILE = '''\ -.. %(project)s documentation master file, created by sphinx-quickstart on %(now)s. +.. %(project)s documentation master file, created by + sphinx-quickstart on %(now)s. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -257,50 +263,62 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes \ +linkcheck doctest help: \t@echo "Please use \\`make <target>' where <target> is one of" \t@echo " html to make standalone HTML files" +\t@echo " dirhtml to make HTML files named index.html in directories" \t@echo " pickle to make pickle files" \t@echo " json to make JSON files" \t@echo " htmlhelp to make HTML files and a HTML help project" +\t@echo " qthelp to make HTML files and a qthelp project" \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" -\t@echo " changes to make an overview over all changed/added/deprecated items" +\t@echo " changes to make an overview of all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" +\t@echo " doctest to run all doctests embedded in the documentation \ +(if enabled)" clean: \t-rm -rf %(rbuilddir)s/* html: -\tmkdir -p %(rbuilddir)s/html %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) %(rbuilddir)s/html \t@echo \t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html." +dirhtml: +\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) %(rbuilddir)s/dirhtml +\t@echo +\t@echo "Build finished. The HTML pages are in %(rbuilddir)s/dirhtml." + pickle: -\tmkdir -p %(rbuilddir)s/pickle %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle \t@echo \t@echo "Build finished; now you can process the pickle files." -web: pickle - json: -\tmkdir -p %(rbuilddir)s/json %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) %(rbuilddir)s/json \t@echo \t@echo "Build finished; now you can process the JSON files." htmlhelp: -\tmkdir -p %(rbuilddir)s/htmlhelp %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) %(rbuilddir)s/htmlhelp \t@echo \t@echo "Build finished; now you can run HTML Help Workshop with the" \\ \t ".hhp project file in %(rbuilddir)s/htmlhelp." +qthelp: +\t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) %(rbuilddir)s/qthelp +\t@echo +\t@echo "Build finished; now you can run "qcollectiongenerator" with the" \\ +\t ".qhcp project file in %(rbuilddir)s/qthelp, like this:" +\t@echo "# qcollectiongenerator %(rbuilddir)s/qthelp/%(project)s.qhcp" +\t@echo "To view the help file:" +\t@echo "# assistant -collectionFile %(rbuilddir)s/qthelp/%(project)s.qhc" + latex: -\tmkdir -p %(rbuilddir)s/latex %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex \t@echo \t@echo "Build finished; the LaTeX files are in %(rbuilddir)s/latex." @@ -308,17 +326,135 @@ latex: \t "run these through (pdf)latex." changes: -\tmkdir -p %(rbuilddir)s/changes %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) %(rbuilddir)s/changes \t@echo \t@echo "The overview file is in %(rbuilddir)s/changes." linkcheck: -\tmkdir -p %(rbuilddir)s/linkcheck %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) %(rbuilddir)s/linkcheck \t@echo \t@echo "Link check complete; look for any errors in the above output " \\ \t "or in %(rbuilddir)s/linkcheck/output.txt." + +doctest: +\t$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) %(rbuilddir)s/doctest +\t@echo "Testing of doctests in the sources finished, look at the " \\ +\t "results in %(rbuilddir)s/doctest/output.txt." +''' + +BATCHFILE = '''\ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set ALLSPHINXOPTS=-d %(rbuilddir)s/doctrees %%SPHINXOPTS%% %(rsrcdir)s +if NOT "%%PAPER%%" == "" ( +\tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%% +) + +if "%%1" == "" goto help + +if "%%1" == "help" ( +\t:help +\techo.Please use `make ^<target^>` where ^<target^> is one of +\techo. html to make standalone HTML files +\techo. dirhtml to make HTML files named index.html in directories +\techo. pickle to make pickle files +\techo. json to make JSON files +\techo. htmlhelp to make HTML files and a HTML help project +\techo. qthelp to make HTML files and a qthelp project +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. changes to make an overview over all changed/added/deprecated items +\techo. linkcheck to check all external links for integrity +\techo. doctest to run all doctests embedded in the documentation if enabled +\tgoto end +) + +if "%%1" == "clean" ( +\tfor /d %%%%i in (%(rbuilddir)s\*) do rmdir /q /s %%%%i +\tdel /q /s %(rbuilddir)s\* +\tgoto end +) + +if "%%1" == "html" ( +\t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %(rbuilddir)s/html +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/html. +\tgoto end +) + +if "%%1" == "dirhtml" ( +\t%%SPHINXBUILD%% -b dirhtml %%ALLSPHINXOPTS%% %(rbuilddir)s/dirhtml +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/dirhtml. +\tgoto end +) + +if "%%1" == "pickle" ( +\t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle +\techo. +\techo.Build finished; now you can process the pickle files. +\tgoto end +) + +if "%%1" == "json" ( +\t%%SPHINXBUILD%% -b json %%ALLSPHINXOPTS%% %(rbuilddir)s/json +\techo. +\techo.Build finished; now you can process the JSON files. +\tgoto end +) + +if "%%1" == "htmlhelp" ( +\t%%SPHINXBUILD%% -b htmlhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/htmlhelp +\techo. +\techo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %(rbuilddir)s/htmlhelp. +\tgoto end +) + +if "%%1" == "qthelp" ( +\t%%SPHINXBUILD%% -b qthelp %%ALLSPHINXOPTS%% %(rbuilddir)s/qthelp +\techo. +\techo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %(rbuilddir)s/qthelp, like this: +\techo.^> qcollectiongenerator %(rbuilddir)s\\qthelp\\%(project)s.qhcp +\techo.To view the help file: +\techo.^> assistant -collectionFile %(rbuilddir)s\\qthelp\\%(project)s.ghc +\tgoto end +) + +if "%%1" == "latex" ( +\t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex +\techo. +\techo.Build finished; the LaTeX files are in %(rbuilddir)s/latex. +\tgoto end +) + +if "%%1" == "changes" ( +\t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %(rbuilddir)s/changes +\techo. +\techo.The overview file is in %(rbuilddir)s/changes. +\tgoto end +) + +if "%%1" == "linkcheck" ( +\t%%SPHINXBUILD%% -b linkcheck %%ALLSPHINXOPTS%% %(rbuilddir)s/linkcheck +\techo. +\techo.Link check complete; look for any errors in the above output ^ +or in %(rbuilddir)s/linkcheck/output.txt. +\tgoto end +) + +if "%%1" == "doctest" ( +\t%%SPHINXBUILD%% -b doctest %%ALLSPHINXOPTS%% %(rbuilddir)s/doctest +\techo. +\techo.Testing of doctests in the sources finished, look at the ^ +results in %(rbuilddir)s/doctest/output.txt. +\tgoto end +) + +:end ''' @@ -367,8 +503,9 @@ def do_prompt(d, key, text, default=None, validator=nonempty): if TERM_ENCODING: x = x.decode(TERM_ENCODING) else: - print turquoise('* Note: non-ASCII characters entered and terminal ' - 'encoding unknown -- assuming UTF-8 or Latin-1.') + print turquoise('* Note: non-ASCII characters entered ' + 'and terminal encoding unknown -- assuming ' + 'UTF-8 or Latin-1.') try: x = x.decode('utf-8') except UnicodeDecodeError: @@ -382,6 +519,7 @@ def do_prompt(d, key, text, default=None, validator=nonempty): def inner_main(args): d = {} + texescape.init() if not sys.stdout.isatty() or not color_terminal(): nocolor() @@ -402,23 +540,23 @@ Enter the root path for documentation.''' 'selected root path.') print 'sphinx-quickstart will not overwrite existing Sphinx projects.' print - do_prompt(d, 'path', 'Please enter a new root path (or just Enter to exit)', - '', is_path) + do_prompt(d, 'path', 'Please enter a new root path (or just Enter ' + 'to exit)', '', is_path) if not d['path']: sys.exit(1) print ''' You have two options for placing the build directory for Sphinx output. -Either, you use a directory ".build" within the root path, or you separate +Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path.''' do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n', boolean) + print ''' -Inside the root directory, two more directories will be created; ".templates" -for custom HTML templates and ".static" for custom stylesheets and other -static files. Since the leading dot may be inconvenient for Windows users, -you can enter another prefix (such as "_") to replace the dot.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) +Inside the root directory, two more directories will be created; "_templates" +for custom HTML templates and "_static" for custom stylesheets and other static +files. You can enter another prefix (such as ".") to replace the underscore.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) print ''' The project name will occur in several places in the built documentation.''' @@ -449,26 +587,43 @@ Please indicate if you want to use one of the following Sphinx extensions:''' 'from modules (y/N)', 'n', boolean) do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets ' 'in doctest blocks (y/N)', 'n', boolean) - do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx documentation ' - 'of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx ' + 'documentation of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_todo', 'todo: write "todo" entries ' + 'that can be shown or hidden on build (y/N)', 'n', boolean) + do_prompt(d, 'ext_coverage', 'coverage: checks for documentation ' + 'coverage (y/N)', 'n', boolean) + do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered ' + 'as PNG images (y/N)', 'n', boolean) + do_prompt(d, 'ext_jsmath', 'jsmath: include math, rendered in the ' + 'browser by JSMath (y/N)', 'n', boolean) + if d['ext_pngmath'] and d['ext_jsmath']: + print '''Note: pngmath and jsmath cannot be enabled at the same time. +pngmath has been deselected.''' + do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of ' + 'content based on config values (y/N)', 'n', boolean) print ''' -If you are under Unix, a Makefile can be generated for you so that you +A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly.''' - do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', - os.name == 'posix' and 'y' or 'n', boolean) + do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', + 'y', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() d['underline'] = len(d['project']) * '=' d['extensions'] = ', '.join( - repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx') + repr('sphinx.ext.' + name) + for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage', + 'pngmath', 'jsmath', 'ifconfig') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] - d['author_texescaped'] = unicode(d['author']).translate(tex_escape_map) + d['author_texescaped'] = unicode(d['author']).\ + translate(texescape.tex_escape_map) d['project_doc'] = d['project'] + ' Documentation' - d['project_doc_texescaped'] = \ - unicode(d['project'] + ' Documentation').translate(tex_escape_map) + d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\ + translate(texescape.tex_escape_map) if not path.isdir(d['path']): mkdir_p(d['path']) @@ -508,11 +663,19 @@ directly.''' f.write((MAKEFILE % d).encode('utf-8')) f.close() + create_batch = d['batchfile'].upper() in ('Y', 'YES') + if create_batch: + d['rsrcdir'] = separate and 'source' or '.' + d['rbuilddir'] = separate and 'build' or d['dot'] + 'build' + f = open(path.join(d['path'], 'make.bat'), 'w') + f.write((BATCHFILE % d).encode('utf-8')) + f.close() + print print bold('Finished: An initial directory structure has been created.') print ''' You should now populate your master file %s and create other documentation -source files. ''' % masterfile + (create_makefile and '''\ +source files. ''' % masterfile + ((create_makefile or create_batch) and '''\ Use the Makefile to build the docs, like so: make builder ''' or '''\ |