diff --git a/.gitignore b/.gitignore index fb9baf35..adc129e0 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ _mailinglist .tox .cache/ .idea/ +docs/_build/ # Coverage reports htmlcov diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 3d7df149..00000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "docs/_themes"] - path = docs/_themes - url = https://github.com/mitsuhiko/flask-sphinx-themes.git diff --git a/CHANGES b/CHANGES index 9260537a..0c0b162f 100644 --- a/CHANGES +++ b/CHANGES @@ -524,7 +524,7 @@ Released on July 27th 2010, codename Whisky prefix. This makes it possible to bind a whole module to a configurable subdomain. -.. _blinker: https://pypi.python.org/pypi/blinker +.. _blinker: https://pypi.org/project/blinker/ Version 0.5.2 ------------- diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index e35d8850..00000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build diff --git a/docs/Makefile b/docs/Makefile index 52d78d9e..fc19e49d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,118 +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 = Flask +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 epub latex 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 " 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/Flask.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flask.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) _build/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Flask" - @echo "# ln -s _build/devhelp $$HOME/.local/share/devhelp/Flask" - @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) _build/latex - @echo "Running LaTeX files through pdflatex..." - make -C _build/latex all-pdf - @echo "pdflatex finished; the PDF files are in _build/latex." - -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) \ No newline at end of file diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html deleted file mode 100644 index ec1608fd..00000000 --- a/docs/_templates/sidebarintro.html +++ /dev/null @@ -1,22 +0,0 @@ -

About Flask

-

- Flask is a micro webdevelopment framework for Python. You are currently - looking at the documentation of the development version. -

-

Other Formats

-

- You can download the documentation in other formats as well: -

- -

Useful Links

- diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html deleted file mode 100644 index 3bc7f762..00000000 --- a/docs/_templates/sidebarlogo.html +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/docs/_themes b/docs/_themes deleted file mode 160000 index 3d964b66..00000000 --- a/docs/_themes +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 3d964b660442e23faedf801caed6e3c7bd42d5c9 diff --git a/docs/api.rst b/docs/api.rst index d77da3de..49adb4a8 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -703,7 +703,7 @@ The following signals exist in Flask: operations, including connecting. -.. _blinker: https://pypi.python.org/pypi/blinker +.. _blinker: https://pypi.org/project/blinker/ Class-Based Views diff --git a/docs/conf.py b/docs/conf.py index b37427a8..a1d10ed2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,284 +1,96 @@ # -*- coding: utf-8 -*- -# -# Flask documentation build configuration file, created by -# sphinx-quickstart on Tue Apr 6 15:24:58 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 __future__ import print_function -from datetime import datetime -import os -import sys -import pkg_resources -# 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.join(os.path.dirname(__file__), '_themes')) -sys.path.append(os.path.dirname(__file__)) +import inspect +import re -# -- General configuration ----------------------------------------------------- +from pallets_sphinx_themes import ProjectLink, get_version -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# Project -------------------------------------------------------------- -# 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', - 'flaskdocext' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' +project = 'Flask' +copyright = '2010 Pallets Team' +author = 'Pallets Team' +release, version = get_version('Flask') -# The encoding of source files. -#source_encoding = 'utf-8-sig' +# General -------------------------------------------------------------- -# The master toctree document. master_doc = 'index' -# General information about the project. -project = u'Flask' -copyright = u'2010 - {0}, Armin Ronacher'.format(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. -try: - release = pkg_resources.get_distribution('Flask').version -except pkg_resources.DistributionNotFound: - print('Flask must be installed to build the documentation.') - print('Install from source using `pip install -e .` in a virtualenv.') - sys.exit(1) - -if 'dev' in release: - release = ''.join(release.partition('dev')[:2]) - -version = '.'.join(release.split('.')[:2]) - -# 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 = {} - -# 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 = None - -# 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. Do not set, template magic! -#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 = '_static/flask-favicon.ico' - -# 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'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinxcontrib.log_cabinet', +] -# 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' +intersphinx_mapping = { + # 'python': ('https://docs.python.org/3/', None), + # 'werkzeug': ('http://werkzeug.pocoo.org/docs/', None), + # 'click': ('http://click.pocoo.org/', None), + # 'jinja': ('http://jinja.pocoo.org/docs/', None), + # 'itsdangerous': ('https://pythonhosted.org/itsdangerous', None), + # 'sqlalchemy': ('https://docs.sqlalchemy.org/en/latest/', None), + # 'wtforms': ('https://wtforms.readthedocs.io/en/latest/', None), + # 'blinker': ('https://pythonhosted.org/blinker/', None), +} -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True +# HTML ----------------------------------------------------------------- -# Custom sidebar templates, maps document names to template names. +html_theme = 'flask' +html_context = { + 'project_links': [ + ProjectLink('Flask Website', 'https://palletsprojects.com/p/flask/'), + ProjectLink('PyPI releases', 'https://pypi.org/project/Flask/'), + ProjectLink('Source Code', 'https://github.com/pallets/flask/'), + ProjectLink( + 'Issue Tracker', 'https://github.com/pallets/flask/issues/'), + ], + 'canonical_url': 'http://flask.pocoo.org/docs/{}/'.format(version), + 'carbon_ads_args': 'zoneid=1673&serve=C6AILKT&placement=pocooorg', +} html_sidebars = { 'index': [ - 'sidebarintro.html', - 'sourcelink.html', - 'searchbox.html' + 'project.html', + 'versions.html', + 'searchbox.html', ], '**': [ - 'sidebarlogo.html', 'localtoc.html', 'relations.html', - 'sourcelink.html', - 'searchbox.html' + 'versions.html', + 'carbon_ads.html', + 'searchbox.html', ] } +html_static_path = ['_static'] +html_favicon = '_static/flask-favicon.ico' +html_logo = '_static/flask.png' +html_additional_pages = { + '404': '404.html', +} +html_show_sourcelink = False -# 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_use_modindex = False - -# 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 = False - -# 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 = '' - -# 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 = 'Flaskdoc' - - -# -- Options for LaTeX output -------------------------------------------------- +# LaTeX ---------------------------------------------------------------- -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('latexindex', 'Flask.tex', u'Flask Documentation', u'Armin Ronacher', 'manual'), + (master_doc, 'Flask.tex', 'Flask Documentation', 'Pallets Team', 'manual'), ] - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. latex_use_modindex = False - latex_elements = { - 'fontpkg': r'\usepackage{mathpazo}', 'papersize': 'a4paper', 'pointsize': '12pt', - 'preamble': r'\usepackage{flaskstyle}' + 'fontpkg': r'\usepackage{mathpazo}', + 'preamble': r'\usepackage{flaskstyle}', } latex_use_parts = True - latex_additional_files = ['flaskstyle.sty', 'logo.pdf'] +# linkcheck ------------------------------------------------------------ -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -#epub_title = '' -#epub_author = '' -#epub_publisher = '' -#epub_copyright = '' - -# 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 = [] +linkcheck_anchors = False -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 +# Local Extensions ----------------------------------------------------- -intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'werkzeug': ('http://werkzeug.pocoo.org/docs/', None), - 'click': ('http://click.pocoo.org/', None), - 'jinja': ('http://jinja.pocoo.org/docs/', None), - 'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest/', None), - 'wtforms': ('https://wtforms.readthedocs.io/en/latest/', None), - 'blinker': ('https://pythonhosted.org/blinker/', None) -} - -try: - __import__('flask_theme_support') - pygments_style = 'flask_theme_support.FlaskyStyle' - html_theme = 'flask' - html_theme_options = { - 'touch_icon': 'touch-icon.png' - } -except ImportError: - print('-' * 74) - print('Warning: Flask themes unavailable. Building with default theme') - print('If you want the Flask themes, run this command and build again:') - print() - print(' git submodule update --init') - print('-' * 74) - - -# unwrap decorators def unwrap_decorators(): import sphinx.util.inspect as inspect import functools @@ -295,5 +107,62 @@ def unwrap_decorators(): return rv functools.update_wrapper = update_wrapper + unwrap_decorators() del unwrap_decorators + + +_internal_mark_re = re.compile(r'^\s*:internal:\s*$(?m)', re.M) + + +def skip_internal(app, what, name, obj, skip, options): + docstring = inspect.getdoc(obj) or '' + + if skip or _internal_mark_re.search(docstring) is not None: + return True + + +def cut_module_meta(app, what, name, obj, options, lines): + """Remove metadata from autodoc output.""" + if what != 'module': + return + + lines[:] = [ + line for line in lines + if not line.startswith((':copyright:', ':license:')) + ] + + +def github_link( + name, rawtext, text, lineno, inliner, options=None, content=None +): + app = inliner.document.settings.env.app + release = app.config.release + base_url = 'https://github.com/pallets/flask/tree/' + + if text.endswith('>'): + words, text = text[:-1].rsplit('<', 1) + words = words.strip() + else: + words = None + + if release.endswith('dev'): + url = '{0}master/{1}'.format(base_url, text) + else: + url = '{0}{1}/{2}'.format(base_url, release, text) + + if words is None: + words = url + + from docutils.nodes import reference + from docutils.parsers.rst.roles import set_classes + options = options or {} + set_classes(options) + node = reference(rawtext, words, refuri=url, **options) + return [node], [] + + +def setup(app): + app.connect('autodoc-skip-member', skip_internal) + app.connect('autodoc-process-docstring', cut_module_meta) + app.add_role('gh', github_link) diff --git a/docs/deploying/fastcgi.rst b/docs/deploying/fastcgi.rst index c0beae0c..2d349896 100644 --- a/docs/deploying/fastcgi.rst +++ b/docs/deploying/fastcgi.rst @@ -237,4 +237,4 @@ python path. Common problems are: .. _nginx: http://nginx.org/ .. _lighttpd: http://www.lighttpd.net/ .. _cherokee: http://cherokee-project.com/ -.. _flup: https://pypi.python.org/pypi/flup +.. _flup: https://pypi.org/project/flup/ diff --git a/docs/deploying/mod_wsgi.rst b/docs/deploying/mod_wsgi.rst index 0f4af6c3..7d5720ed 100644 --- a/docs/deploying/mod_wsgi.rst +++ b/docs/deploying/mod_wsgi.rst @@ -134,7 +134,7 @@ For more information consult the `mod_wsgi documentation`_. .. _mod_wsgi: https://github.com/GrahamDumpleton/mod_wsgi .. _installation instructions: http://modwsgi.readthedocs.io/en/develop/installation.html -.. _virtual python: https://pypi.python.org/pypi/virtualenv +.. _virtual python: https://pypi.org/project/virtualenv/ .. _mod_wsgi documentation: http://modwsgi.readthedocs.io/en/develop/index.html Troubleshooting diff --git a/docs/extensions.rst b/docs/extensions.rst index 6deb9652..b30ab5cf 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -29,30 +29,7 @@ Building Extensions ------------------- While `Flask Extension Registry`_ contains many Flask extensions, you may not find -an extension that fits your need. If this is the case, you can always create your own. +an extension that fits your need. If this is the case, you can always create your own. Consider reading :ref:`extension-dev` to develop your own Flask extension. -Flask Before 0.8 ----------------- - -If you are using Flask 0.7 or earlier the :data:`flask.ext` package will not -exist, instead you have to import from ``flaskext.foo`` or ``flask_foo`` -depending on how the extension is distributed. If you want to develop an -application that supports Flask 0.7 or earlier you should still import -from the :data:`flask.ext` package. We provide you with a compatibility -module that provides this package for older versions of Flask. You can -download it from GitHub: `flaskext_compat.py`_ - -And here is how you can use it:: - - import flaskext_compat - flaskext_compat.activate() - - from flask.ext import foo - -Once the ``flaskext_compat`` module is activated the :data:`flask.ext` will -exist and you can start importing from there. - - .. _Flask Extension Registry: http://flask.pocoo.org/extensions/ -.. _flaskext_compat.py: https://raw.githubusercontent.com/pallets/flask/master/scripts/flaskext_compat.py diff --git a/docs/flaskdocext.py b/docs/flaskdocext.py deleted file mode 100644 index db4cfd20..00000000 --- a/docs/flaskdocext.py +++ /dev/null @@ -1,16 +0,0 @@ -import re -import inspect - - -_internal_mark_re = re.compile(r'^\s*:internal:\s*$(?m)') - - -def skip_member(app, what, name, obj, skip, options): - docstring = inspect.getdoc(obj) - if skip: - return True - return _internal_mark_re.search(docstring or '') is not None - - -def setup(app): - app.connect('autodoc-skip-member', skip_member) diff --git a/docs/flaskext.py b/docs/flaskext.py deleted file mode 100644 index 33f47449..00000000 --- a/docs/flaskext.py +++ /dev/null @@ -1,86 +0,0 @@ -# flasky extensions. flasky pygments style based on tango style -from pygments.style import Style -from pygments.token import Keyword, Name, Comment, String, Error, \ - Number, Operator, Generic, Whitespace, Punctuation, Other, Literal - - -class FlaskyStyle(Style): - background_color = "#f8f8f8" - default_style = "" - - styles = { - # No corresponding class for the following: - #Text: "", # class: '' - Whitespace: "underline #f8f8f8", # class: 'w' - Error: "#a40000 border:#ef2929", # class: 'err' - Other: "#000000", # class 'x' - - Comment: "italic #8f5902", # class: 'c' - Comment.Preproc: "noitalic", # class: 'cp' - - Keyword: "bold #004461", # class: 'k' - Keyword.Constant: "bold #004461", # class: 'kc' - Keyword.Declaration: "bold #004461", # class: 'kd' - Keyword.Namespace: "bold #004461", # class: 'kn' - Keyword.Pseudo: "bold #004461", # class: 'kp' - Keyword.Reserved: "bold #004461", # class: 'kr' - Keyword.Type: "bold #004461", # class: 'kt' - - Operator: "#582800", # class: 'o' - Operator.Word: "bold #004461", # class: 'ow' - like keywords - - Punctuation: "bold #000000", # class: 'p' - - # because special names such as Name.Class, Name.Function, etc. - # are not recognized as such later in the parsing, we choose them - # to look the same as ordinary variables. - Name: "#000000", # class: 'n' - Name.Attribute: "#c4a000", # class: 'na' - to be revised - Name.Builtin: "#004461", # class: 'nb' - Name.Builtin.Pseudo: "#3465a4", # class: 'bp' - Name.Class: "#000000", # class: 'nc' - to be revised - Name.Constant: "#000000", # class: 'no' - to be revised - Name.Decorator: "#888", # class: 'nd' - to be revised - Name.Entity: "#ce5c00", # class: 'ni' - Name.Exception: "bold #cc0000", # class: 'ne' - Name.Function: "#000000", # class: 'nf' - Name.Property: "#000000", # class: 'py' - Name.Label: "#f57900", # class: 'nl' - Name.Namespace: "#000000", # class: 'nn' - to be revised - Name.Other: "#000000", # class: 'nx' - Name.Tag: "bold #004461", # class: 'nt' - like a keyword - Name.Variable: "#000000", # class: 'nv' - to be revised - Name.Variable.Class: "#000000", # class: 'vc' - to be revised - Name.Variable.Global: "#000000", # class: 'vg' - to be revised - Name.Variable.Instance: "#000000", # class: 'vi' - to be revised - - Number: "#990000", # class: 'm' - - Literal: "#000000", # class: 'l' - Literal.Date: "#000000", # class: 'ld' - - String: "#4e9a06", # class: 's' - String.Backtick: "#4e9a06", # class: 'sb' - String.Char: "#4e9a06", # class: 'sc' - String.Doc: "italic #8f5902", # class: 'sd' - like a comment - String.Double: "#4e9a06", # class: 's2' - String.Escape: "#4e9a06", # class: 'se' - String.Heredoc: "#4e9a06", # class: 'sh' - String.Interpol: "#4e9a06", # class: 'si' - String.Other: "#4e9a06", # class: 'sx' - String.Regex: "#4e9a06", # class: 'sr' - String.Single: "#4e9a06", # class: 's1' - String.Symbol: "#4e9a06", # class: 'ss' - - Generic: "#000000", # class: 'g' - Generic.Deleted: "#a40000", # class: 'gd' - Generic.Emph: "italic #000000", # class: 'ge' - Generic.Error: "#ef2929", # class: 'gr' - Generic.Heading: "bold #000080", # class: 'gh' - Generic.Inserted: "#00A000", # class: 'gi' - Generic.Output: "#888", # class: 'go' - Generic.Prompt: "#745334", # class: 'gp' - Generic.Strong: "bold #000000", # class: 'gs' - Generic.Subheading: "bold #800080", # class: 'gu' - Generic.Traceback: "bold #a40000", # class: 'gt' - } diff --git a/docs/index.rst b/docs/index.rst index 617104ee..63789176 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Welcome to Flask .. image:: _static/logo-full.png :alt: Flask: web development, one drop at a time :class: floatingflask + :align: right Welcome to Flask's documentation. This documentation is divided into different parts. I recommend that you get started with diff --git a/docs/make.bat b/docs/make.bat index 3ad12879..54ae50aa 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,139 +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=Flask 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. 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 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + 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; now you can process the JSON files. - goto end + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 ) -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 -) +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +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\Flask.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Flask.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% _build/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" == "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/patterns/distribute.rst b/docs/patterns/distribute.rst index 72cc25d6..f6443c2e 100644 --- a/docs/patterns/distribute.rst +++ b/docs/patterns/distribute.rst @@ -173,5 +173,5 @@ folder instead of copying the data over. You can then continue to work on the code without having to run ``install`` again after each change. -.. _pip: https://pypi.python.org/pypi/pip +.. _pip: https://pypi.org/project/pip/ .. _Setuptools: https://pythonhosted.org/setuptools diff --git a/docs/patterns/jquery.rst b/docs/patterns/jquery.rst index d136d5b4..c44fd632 100644 --- a/docs/patterns/jquery.rst +++ b/docs/patterns/jquery.rst @@ -162,7 +162,5 @@ explanation of the little bit of code above: argument. Note that we can use the `$SCRIPT_ROOT` variable here that we set earlier. -If you don't get the whole picture, download the `sourcecode -for this example -`_ -from GitHub. +If you don't get the whole picture, download the :gh:`sourcecode for +this example ` from GitHub. diff --git a/docs/patterns/sqlalchemy.rst b/docs/patterns/sqlalchemy.rst index e8215317..8c56868f 100644 --- a/docs/patterns/sqlalchemy.rst +++ b/docs/patterns/sqlalchemy.rst @@ -20,7 +20,7 @@ there is a Flask extension that handles that for you. This is recommended if you want to get started quickly. You can download `Flask-SQLAlchemy`_ from `PyPI -`_. +`_. .. _Flask-SQLAlchemy: http://pythonhosted.org/Flask-SQLAlchemy/ diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index 2649cad6..ce96d4ef 100644 --- a/docs/patterns/wtforms.rst +++ b/docs/patterns/wtforms.rst @@ -17,7 +17,7 @@ forms. The `Flask-WTF`_ extension expands on this pattern and adds a few little helpers that make working with forms and Flask more fun. You can get it from `PyPI - `_. + `_. .. _Flask-WTF: http://pythonhosted.org/Flask-WTF/ diff --git a/docs/signals.rst b/docs/signals.rst index 2426e920..4943fd84 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -187,4 +187,4 @@ Core Signals Take a look at :ref:`core-signals-list` for a list of all builtin signals. -.. _blinker: https://pypi.python.org/pypi/blinker +.. _blinker: https://pypi.org/project/blinker/ diff --git a/docs/testing.rst b/docs/testing.rst index 6fd7b504..e5fa50e5 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -21,10 +21,7 @@ The Application First, we need an application to test; we will use the application from the :ref:`tutorial`. If you don't have that application yet, get the -sources from `the examples`_. - -.. _the examples: - https://github.com/pallets/flask/tree/master/examples/flaskr/ +sources from :gh:`the examples `. The Testing Skeleton -------------------- @@ -196,7 +193,7 @@ suite. .. _MiniTwit Example: - https://github.com/pallets/flask/tree/master/examples/minitwit/ + https://github.com/pallets/flask/tree/0.12.3/examples/minitwit/ Other Testing Tricks diff --git a/docs/tutorial/dbcon.rst b/docs/tutorial/dbcon.rst index 2dd3d7be..053f0804 100644 --- a/docs/tutorial/dbcon.rst +++ b/docs/tutorial/dbcon.rst @@ -66,10 +66,8 @@ Continue to :ref:`tutorial-dbinit`. ``get_db`` and ``close_db`` functions below your existing ``connect_db`` function (following the tutorial line-by-line). - If you need a moment to find your bearings, take a look at how the `example - source`_ is organized. In Flask, you can put all of your application code - into a single Python module. You don't have to, and if your app :ref:`grows - larger `, it's a good idea not to. - -.. _example source: - https://github.com/pallets/flask/tree/master/examples/flaskr/ + If you need a moment to find your bearings, take a look at how the + :gh:`example source ` is organized. In Flask, you + can put all of your application code into a single Python module. + You don't have to, and if your app + :ref:`grows larger `, it's a good idea not to. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index f0a583e0..6fed5298 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -12,10 +12,7 @@ as a database (which comes out of the box with Python) so there is nothing else you need. If you want the full source code in advance or for comparison, check out -the `example source`_. - -.. _example source: - https://github.com/pallets/flask/tree/master/examples/flaskr/ +the :gh:`example source `. .. toctree:: :maxdepth: 2 diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 41b70f03..a730062a 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -215,7 +215,7 @@ good. To apply the upgrade script do the following: 1. Download the script: `flask-07-upgrade.py - `_ + `_ 2. Run it in the directory of your application:: python flask-07-upgrade.py > patchfile.diff