diff --git a/docs/Makefile b/docs/Makefile index 9bca27fe9..6e3c9b90d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,130 +1,20 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = +SPHINXPROJ = Jinja +SOURCEDIR = . BUILDDIR = _build -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Classy.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Classy.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Classy" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Classy" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -latexpdf: latex - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." +.PHONY: help Makefile -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/click-icon.png b/docs/_static/click-icon.png new file mode 100644 index 000000000..b883cfaa1 Binary files /dev/null and b/docs/_static/click-icon.png differ diff --git a/docs/_static/click-small@2x.png b/docs/_static/click-logo-sidebar.png similarity index 100% rename from docs/_static/click-small@2x.png rename to docs/_static/click-logo-sidebar.png diff --git a/docs/_static/click@2x.png b/docs/_static/click-logo.png similarity index 100% rename from docs/_static/click@2x.png rename to docs/_static/click-logo.png diff --git a/docs/_static/click-small.png b/docs/_static/click-small.png deleted file mode 100644 index f101a8a31..000000000 Binary files a/docs/_static/click-small.png and /dev/null differ diff --git a/docs/_static/click.png b/docs/_static/click.png deleted file mode 100644 index 64c62f16e..000000000 Binary files a/docs/_static/click.png and /dev/null differ diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html deleted file mode 100644 index 0041190fb..000000000 --- a/docs/_templates/sidebarintro.html +++ /dev/null @@ -1,13 +0,0 @@ -

About

-

- Click is a Python package for creating beautiful command line interfaces in a - composable way with as little amount of code as necessary. It’s the “Command - Line Interface Creation Kit”. -

-

Useful Links

- diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html deleted file mode 100644 index 55c462960..000000000 --- a/docs/_templates/sidebarlogo.html +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/docs/clickdoctools.py b/docs/clickdoctools.py deleted file mode 100644 index 36723fa22..000000000 --- a/docs/clickdoctools.py +++ /dev/null @@ -1,275 +0,0 @@ -import os -import sys -import click -import shutil -import tempfile -import contextlib -import subprocess - -try: - from StringIO import StringIO -except ImportError: - from io import StringIO - -from docutils import nodes -from docutils.statemachine import ViewList - -from sphinx.domains import Domain -from sphinx.util.compat import Directive - - -class EchoingStdin(object): - - def __init__(self, input, output): - self._input = input - self._output = output - - def __getattr__(self, x): - return getattr(self._input, x) - - def _echo(self, rv): - mark = False - if rv.endswith('\xff'): - rv = rv[:-1] - mark = True - self._output.write(rv) - if mark: - self._output.write('^D\n') - return rv - - def read(self, n=-1): - return self._echo(self._input.read(n)) - - def readline(self, n=-1): - return self._echo(self._input.readline(n)) - - def readlines(self): - return [self._echo(x) for x in self._input.readlines()] - - def __iter__(self): - return iter(self._echo(x) for x in self._input) - - -@contextlib.contextmanager -def fake_modules(): - old_call = subprocess.call - def dummy_call(*args, **kwargs): - with tempfile.TemporaryFile('wb+') as f: - kwargs['stdout'] = f - kwargs['stderr'] = f - rv = subprocess.Popen(*args, **kwargs).wait() - f.seek(0) - click.echo(f.read().decode('utf-8', 'replace').rstrip()) - return rv - subprocess.call = dummy_call - try: - yield - finally: - subprocess.call = old_call - - -@contextlib.contextmanager -def isolation(input=None, env=None): - if isinstance(input, unicode): - input = input.encode('utf-8') - input = StringIO(input or '') - output = StringIO() - sys.stdin = EchoingStdin(input, output) - sys.stdin.encoding = 'utf-8' - - def visible_input(prompt=None): - sys.stdout.write(prompt or '') - val = input.readline().rstrip('\r\n') - sys.stdout.write(val + '\n') - sys.stdout.flush() - return val - - def hidden_input(prompt=None): - sys.stdout.write((prompt or '') + '\n') - sys.stdout.flush() - return input.readline().rstrip('\r\n') - - sys.stdout = output - sys.stderr = output - old_visible_prompt_func = click.termui.visible_prompt_func - old_hidden_prompt_func = click.termui.hidden_prompt_func - click.termui.visible_prompt_func = visible_input - click.termui.hidden_prompt_func = hidden_input - - old_env = {} - try: - if env: - for key, value in env.iteritems(): - old_env[key] = os.environ.get(value) - os.environ[key] = value - yield output - finally: - for key, value in old_env.iteritems(): - if value is None: - try: - del os.environ[key] - except Exception: - pass - else: - os.environ[key] = value - sys.stdout = sys.__stdout__ - sys.stderr = sys.__stderr__ - click.termui.visible_prompt_func = old_visible_prompt_func - click.termui.hidden_prompt_func = old_hidden_prompt_func - - -@contextlib.contextmanager -def isolated_filesystem(): - cwd = os.getcwd() - t = tempfile.mkdtemp() - os.chdir(t) - try: - yield - finally: - os.chdir(cwd) - try: - shutil.rmtree(t) - except (OSError, IOError): - pass - - -class ExampleRunner(object): - - def __init__(self): - self.namespace = { - 'click': click, - '__file__': 'dummy.py', - } - - def declare(self, source): - with fake_modules(): - code = compile(source, '', 'exec') - eval(code, self.namespace) - - def run(self, source): - code = compile(source, '', 'exec') - buffer = [] - - def invoke(cmd, args=None, prog_name=None, - input=None, terminate_input=False, env=None, - **extra): - if env: - for key, value in sorted(env.items()): - if ' ' in value: - value = '"%s"' % value - buffer.append('$ export %s=%s' % (key, value)) - args = args or [] - if prog_name is None: - prog_name = cmd.name.replace('_', '-') - buffer.append(('$ %s %s' % ( - prog_name, - ' '.join(('"%s"' % x) if ' ' in x else x for x in args) - )).rstrip()) - if isinstance(input, (tuple, list)): - input = '\n'.join(input) + '\n' - if terminate_input: - input += '\xff' - with isolation(input=input, env=env) as output: - try: - cmd.main(args=args, prog_name=prog_name.split()[-1], - **extra) - except SystemExit: - pass - buffer.extend(output.getvalue().splitlines()) - - def println(text=''): - buffer.append(text) - - eval(code, self.namespace, { - 'invoke': invoke, - 'println': println, - 'isolated_filesystem': isolated_filesystem, - }) - return buffer - - def close(self): - pass - - -def parse_rst(state, content_offset, doc): - node = nodes.section() - # hack around title style bookkeeping - surrounding_title_styles = state.memo.title_styles - surrounding_section_level = state.memo.section_level - state.memo.title_styles = [] - state.memo.section_level = 0 - state.nested_parse(doc, content_offset, node, match_titles=1) - state.memo.title_styles = surrounding_title_styles - state.memo.section_level = surrounding_section_level - return node.children - - -def get_example_runner(document): - runner = getattr(document, 'click_example_runner', None) - if runner is None: - runner = document.click_example_runner = ExampleRunner() - return runner - - -class ExampleDirective(Directive): - has_content = True - required_arguments = 0 - optional_arguments = 0 - final_argument_whitespace = False - - def run(self): - doc = ViewList() - runner = get_example_runner(self.state.document) - try: - runner.declare('\n'.join(self.content)) - except: - runner.close() - raise - doc.append('.. sourcecode:: python', '') - doc.append('', '') - for line in self.content: - doc.append(' ' + line, '') - return parse_rst(self.state, self.content_offset, doc) - - -class RunExampleDirective(Directive): - has_content = True - required_arguments = 0 - optional_arguments = 0 - final_argument_whitespace = False - - def run(self): - doc = ViewList() - runner = get_example_runner(self.state.document) - try: - rv = runner.run('\n'.join(self.content)) - except: - runner.close() - raise - doc.append('.. sourcecode:: text', '') - doc.append('', '') - for line in rv: - doc.append(' ' + line, '') - return parse_rst(self.state, self.content_offset, doc) - - -class ClickDomain(Domain): - name = 'click' - label = 'Click' - directives = { - 'example': ExampleDirective, - 'run': RunExampleDirective, - } - - -def delete_example_runner_state(app, doctree): - runner = getattr(doctree, 'click_example_runner', None) - if runner is not None: - runner.close() - del doctree.click_example_runner - - -def setup(app): - app.add_domain(ClickDomain) - - app.connect('doctree-read', delete_example_runner_state) diff --git a/docs/conf.py b/docs/conf.py index dd699953a..4ecc39fee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,219 +1,60 @@ -# -*- coding: utf-8 -*- -# -# click documentation build configuration file, created by -# sphinx-quickstart on Mon Apr 26 19:53:01 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +from pallets_sphinx_themes import ProjectLink, get_version -import sys, os -import datetime +# Project -------------------------------------------------------------- -# 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('..')) -sys.path.append(os.path.abspath('.')) +project = "Click" +copyright = "2014 Pallets Team" +author = "Pallets Team" +release, version = get_version("Click", version_length=1) -# -- General configuration ----------------------------------------------------- +# General -------------------------------------------------------------- -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +master_doc = "index" +extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "pallets_sphinx_themes"] +intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)} -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', - 'clickdoctools'] +# HTML ----------------------------------------------------------------- -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'click' -copyright = u'%d, Armin Ronacher' % datetime.datetime.utcnow().year - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '1.0' -# The full version, including alpha/beta/rc tags. -release = '1.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- 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' - -# 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 = { +html_theme = "click" +html_theme_options = {"index_sidebar_logo": False} +html_context = { + "project_links": [ + ProjectLink("Donate to Pallets", "https://palletsprojects.com/donate"), + ProjectLink("Click Website", "https://palletsprojects.com/p/click/"), + ProjectLink("PyPI releases", "https://pypi.org/project/Click/"), + ProjectLink("Source Code", "https://github.com/pallets/click/"), + ProjectLink("Issue Tracker", "https://github.com/pallets/click/issues/"), + ] } - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = ['_themes'] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -html_title = 'click' - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. html_sidebars = { - 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'], - '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', - 'sourcelink.html', 'searchbox.html'] + "index": ["project.html", "versions.html", "searchbox.html"], + "**": ["localtoc.html", "relations.html", "versions.html", "searchbox.html"], } +singlehtml_sidebars = {"index": ["project.html", "versions.html", "localtoc.html"]} +html_static_path = ["_static"] +html_favicon = "_static/click-icon.png" +html_logo = "_static/click-logo-sidebar.png" +html_title = "{} Documentation ({})".format(project, version) +html_show_sourcelink = False +html_domain_indices = False +html_experimental_html5_writer = True -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# 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 tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' +# LaTeX ---------------------------------------------------------------- -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'clickdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'click.tex', u'click documentation', - u'Armin Ronacher', 'manual'), + (master_doc, "Click.tex", "Click Documentation", "Pallets Team", "manual") ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None +# theme compatibility -------------------------------------------------- -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' +def setup(app): + from click.testing import CliRunner -# Documents to append as an appendix to all manuals. -#latex_appendices = [] + orig_invoke = CliRunner.invoke -# If false, no module index is generated. -#latex_domain_indices = True + def invoke(self, *args, **kwargs): + kwargs.pop("prog_name", None) + return orig_invoke(self, *args, **kwargs) - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'click', u'click documentation', - [u'Armin Ronacher'], 1) -] - -intersphinx_mapping = { - 'http://docs.python.org/dev': None -} + CliRunner.invoke = invoke diff --git a/docs/index.rst b/docs/index.rst index 5bfea5de0..b7c00f7fd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,12 @@ -Welcome to the Click Documentation -================================== +.. rst-class:: hide-header + +Welcome to Click +================ + +.. image:: _static/click-logo.png + :align: center + :scale: 50% + :target: https://palletsprojects.com/p/click/ Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It's the "Command @@ -50,8 +57,8 @@ You can get the library directly from PyPI:: pip install click -Documentation Contents ----------------------- +Documentation +------------- This part of the documentation guides you through all of the library's usage patterns. diff --git a/docs/make.bat b/docs/make.bat index 1e941d8ca..147946324 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,155 +1,36 @@ @ECHO OFF +pushd %~dp0 + REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) +set SOURCEDIR=. set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) +set SPHINXPROJ=Jinja if "%1" == "" goto help -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 ) -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Classy.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Classy.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% :end +popd diff --git a/docs/options.rst b/docs/options.rst index 78811177e..1da02c0ee 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -70,7 +70,7 @@ the tuple. For this you can directly specify a tuple as type: .. click:example:: @click.command() - @click.option('--item', type=(unicode, int)) + @click.option('--item', type=(str, int)) def putitem(item): click.echo('name=%s id=%d' % item) @@ -87,7 +87,7 @@ used. The above example is thus equivalent to this: .. click:example:: @click.command() - @click.option('--item', nargs=2, type=click.Tuple([unicode, int])) + @click.option('--item', nargs=2, type=click.Tuple([str, int])) def putitem(item): click.echo('name=%s id=%d' % item) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..dbd475f20 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx~=1.7.7 +Pallets-Sphinx-Themes~=1.1.0