diff options
Diffstat (limited to 'sphinx/quickstart.py')
| -rw-r--r-- | sphinx/quickstart.py | 230 |
1 files changed, 190 insertions, 40 deletions
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index af1132d5..97ddfc32 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -14,7 +14,8 @@ from os import path TERM_ENCODING = getattr(sys.stdin, 'encoding', None) -from sphinx.util import make_filename +from sphinx import __version__ +from sphinx.util.osutil import make_filename from sphinx.util.console import purple, bold, red, turquoise, \ nocolor, color_terminal from sphinx.util import texescape @@ -45,6 +46,9 @@ import sys, os # -- General configuration ----------------------------------------------------- +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [%(extensions)s] @@ -56,7 +60,7 @@ templates_path = ['%(dot)stemplates'] source_suffix = '%(suffix)s' # The encoding of source files. -#source_encoding = 'utf-8' +#source_encoding = 'utf-8-sig' # The master toctree document. master_doc = '%(master_str)s' @@ -84,12 +88,9 @@ release = '%(release_str)s' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%%B %%d, %%Y' -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = [%(exclude_trees)s] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [%(exclude_patterns)s] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -163,7 +164,7 @@ html_static_path = ['%(dot)sstatic'] #html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +#html_domain_indices = True # If false, no index is generated. #html_use_index = True @@ -174,6 +175,12 @@ html_static_path = ['%(dot)sstatic'] # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = 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 # base URL from which the finished HTML is served. @@ -216,7 +223,56 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_use_modindex = True +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('%(master_str)s', '%(project_manpage)s', u'%(project_doc)s', + [u'%(author_str)s'], 1) +] +''' + +EPUB_CONFIG = ''' + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'%(project_str)s' +epub_author = u'%(author_str)s' +epub_publisher = u'%(author_str)s' +epub_copyright = u'%(copyright_str)s' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 ''' INTERSPHINX_CONFIG = ''' @@ -264,21 +320,27 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes \ -linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp \ +epub latex latexpdf text man 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 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 \ +\t@echo " html to make standalone HTML files" +\t@echo " dirhtml to make HTML files named index.html in directories" +\t@echo " singlehtml to make a single large HTML file" +\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 " devhelp to make HTML files and a Devhelp project" +\t@echo " epub to make an epub" +\t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" +\t@echo " latexpdf to make LaTeX files and run them through pdflatex" +\t@echo " text to make text files" +\t@echo " man to make manual pages" +\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: @@ -294,6 +356,11 @@ dirhtml: \t@echo \t@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +singlehtml: +\t$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml +\t@echo +\t@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + pickle: \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle \t@echo @@ -319,12 +386,43 @@ qthelp: \t@echo "To view the help file:" \t@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/%(project_fn)s.qhc" +devhelp: +\t$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp +\t@echo +\t@echo "Build finished." +\t@echo "To view the help file:" +\t@echo "# mkdir -p $$HOME/.local/share/devhelp/%(project_fn)s" +\t@echo "# ln -s $(BUILDDIR)/devhelp\ + $$HOME/.local/share/devhelp/%(project_fn)s" +\t@echo "# devhelp" + +epub: +\t$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub +\t@echo +\t@echo "Build finished. The epub file is in $(BUILDDIR)/epub." + latex: \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex \t@echo \t@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." -\t@echo "Run \\`make all-pdf' or \\`make all-ps' in that directory to" \\ -\t "run these through (pdf)latex." +\t@echo "Run \\`make' in that directory to run these through (pdf)latex" \\ +\t "(use \\`make latexpdf' here to do that automatically)." + +latexpdf: latex +\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex +\t@echo "Running LaTeX files through pdflatex..." +\tmake -C $(BUILDDIR)/latex all-pdf +\t@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: +\t$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text +\t@echo +\t@echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: +\t$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man +\t@echo +\t@echo "Build finished. The manual pages are in $(BUILDDIR)/man." changes: \t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @@ -348,7 +446,9 @@ BATCHFILE = '''\ REM Command file for Sphinx documentation -set SPHINXBUILD=sphinx-build +if "%%SPHINXBUILD%%" == "" ( +\tset SPHINXBUILD=sphinx-build +) set BUILDDIR=%(rbuilddir)s set ALLSPHINXOPTS=-d %%BUILDDIR%%/doctrees %%SPHINXOPTS%% %(rsrcdir)s if NOT "%%PAPER%%" == "" ( @@ -360,16 +460,21 @@ 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 +\techo. html to make standalone HTML files +\techo. dirhtml to make HTML files named index.html in directories +\techo. singlehtml to make a single large HTML file +\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. devhelp to make HTML files and a Devhelp project +\techo. epub to make an epub +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. text to make text files +\techo. man to make manual pages +\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 ) @@ -393,6 +498,13 @@ if "%%1" == "dirhtml" ( \tgoto end ) +if "%%1" == "singlehtml" ( +\t%%SPHINXBUILD%% -b singlehtml %%ALLSPHINXOPTS%% %%BUILDDIR%%/singlehtml +\techo. +\techo.Build finished. The HTML pages are in %%BUILDDIR%%/singlehtml. +\tgoto end +) + if "%%1" == "pickle" ( \t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %%BUILDDIR%%/pickle \techo. @@ -426,6 +538,20 @@ if "%%1" == "qthelp" ( \tgoto end ) +if "%%1" == "devhelp" ( +\t%%SPHINXBUILD%% -b devhelp %%ALLSPHINXOPTS%% %%BUILDDIR%%/devhelp +\techo. +\techo.Build finished. +\tgoto end +) + +if "%%1" == "epub" ( +\t%%SPHINXBUILD%% -b epub %%ALLSPHINXOPTS%% %%BUILDDIR%%/epub +\techo. +\techo.Build finished. The epub file is in %%BUILDDIR%%/epub. +\tgoto end +) + if "%%1" == "latex" ( \t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %%BUILDDIR%%/latex \techo. @@ -433,6 +559,20 @@ if "%%1" == "latex" ( \tgoto end ) +if "%%1" == "text" ( +\t%%SPHINXBUILD%% -b text %%ALLSPHINXOPTS%% %%BUILDDIR%%/text +\techo. +\techo.Build finished. The text files are in %%BUILDDIR%%/text. +\tgoto end +) + +if "%%1" == "man" ( +\t%%SPHINXBUILD%% -b man %%ALLSPHINXOPTS%% %%BUILDDIR%%/man +\techo. +\techo.Build finished. The manual pages are in %%BUILDDIR%%/man. +\tgoto end +) + if "%%1" == "changes" ( \t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %%BUILDDIR%%/changes \techo. @@ -537,7 +677,7 @@ def inner_main(args): if not color_terminal(): nocolor() - print bold('Welcome to the Sphinx quickstart utility.') + print bold('Welcome to the Sphinx %s quickstart utility.') % __version__ print ''' Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).''' @@ -606,6 +746,11 @@ document is a custom template, you can also set this to another filename.''' 'existing file and press Enter', d['master']) print ''' +Sphinx can also add configuration for epub output:''' + do_prompt(d, 'epub', 'Do you want to use the epub builder (y/N)', + 'n', boolean) + + print ''' Please indicate if you want to use one of the following Sphinx extensions:''' do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings ' 'from modules (y/N)', 'n', boolean) @@ -626,6 +771,8 @@ Please indicate if you want to use one of the following Sphinx extensions:''' pngmath has been deselected.''' do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of ' 'content based on config values (y/N)', 'n', boolean) + do_prompt(d, 'ext_viewcode', 'viewcode: include links to the source code ' + 'of documented Python objects (y/N)', 'n', boolean) print ''' 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 @@ -635,12 +782,13 @@ directly.''' 'y', boolean) d['project_fn'] = make_filename(d['project']) + d['project_manpage'] = d['project_fn'].lower() d['now'] = time.asctime() d['underline'] = len(d['project']) * '=' d['extensions'] = ', '.join( repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage', - 'pngmath', 'jsmath', 'ifconfig') + 'pngmath', 'jsmath', 'ifconfig', 'viewcode') if d['ext_' + name]) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] d['author_texescaped'] = unicode(d['author']).\ @@ -651,7 +799,7 @@ directly.''' # escape backslashes and single quotes in strings that are put into # a Python string literal - for key in ('project', 'copyright', 'author_texescaped', + for key in ('project', 'copyright', 'author', 'author_texescaped', 'project_doc_texescaped', 'version', 'release', 'master'): d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'") @@ -663,15 +811,17 @@ directly.''' mkdir_p(srcdir) if d['sep']: builddir = path.join(d['path'], 'build') - d['exclude_trees'] = '' + d['exclude_patterns'] = '' else: builddir = path.join(srcdir, d['dot'] + 'build') - d['exclude_trees'] = repr(d['dot'] + 'build') + d['exclude_patterns'] = repr(d['dot'] + 'build') mkdir_p(builddir) mkdir_p(path.join(srcdir, d['dot'] + 'templates')) mkdir_p(path.join(srcdir, d['dot'] + 'static')) conf_text = QUICKSTART_CONF % d + if d['epub']: + conf_text += EPUB_CONFIG % d if d['ext_intersphinx']: conf_text += INTERSPHINX_CONFIG |