Browse Source

Merge pull request #2709 from davidism/docs-theme

use theme provided by pallets-sphinx-themes
pull/2711/head
David Lord 7 years ago committed by GitHub
parent
commit
5fba092c22
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 1
      .gitignore
  2. 2
      CHANGES.rst
  3. 1
      docs/.gitignore
  4. 118
      docs/Makefile
  5. 22
      docs/_templates/sidebarintro.html
  6. 3
      docs/_templates/sidebarlogo.html
  7. 2
      docs/api.rst
  8. 322
      docs/conf.py
  9. 2
      docs/deploying/fastcgi.rst
  10. 2
      docs/deploying/mod_wsgi.rst
  11. 5
      docs/extensiondev.rst
  12. 2
      docs/extensions.rst
  13. 16
      docs/flaskdocext.py
  14. 4
      docs/index.rst
  15. 2
      docs/installation.rst
  16. 137
      docs/make.bat
  17. 2
      docs/patterns/caching.rst
  18. 4
      docs/patterns/distribute.rst
  19. 2
      docs/patterns/sqlalchemy.rst
  20. 2
      docs/patterns/wtforms.rst
  21. 2
      docs/signals.rst
  22. 2
      flask/cli.py
  23. 2
      flask/helpers.py
  24. 7
      setup.py
  25. 10
      tox.ini

1
.gitignore vendored

@ -14,6 +14,7 @@ _mailinglist
.cache/ .cache/
.pytest_cache/ .pytest_cache/
.idea/ .idea/
docs/_build/
# Coverage reports # Coverage reports
htmlcov/ htmlcov/

2
CHANGES.rst

@ -711,7 +711,7 @@ Released on July 27th 2010, codename Whisky
prefix. This makes it possible to bind a whole module to a prefix. This makes it possible to bind a whole module to a
configurable subdomain. configurable subdomain.
.. _blinker: https://pypi.python.org/pypi/blinker .. _blinker: https://pypi.org/project/blinker/
Version 0.5.2 Version 0.5.2
------------- -------------

1
docs/.gitignore vendored

@ -1 +0,0 @@
_build

118
docs/Makefile

@ -1,118 +1,20 @@
# Makefile for Sphinx documentation # Minimal makefile for Sphinx documentation
# #
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
PAPER = SPHINXPROJ = Flask
SOURCEDIR = .
BUILDDIR = _build BUILDDIR = _build
# Internal variables. # Put it first so that "make" without argument is like "make help".
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
help: help:
@echo "Please use \`make <target>' where <target> is one of" @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@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."
linkcheck: .PHONY: help Makefile
$(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."
doctest: # Catch-all target: route all unknown targets to Sphinx using the new
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
@echo "Testing of doctests in the sources finished, look at the " \ %: Makefile
"results in $(BUILDDIR)/doctest/output.txt." @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

22
docs/_templates/sidebarintro.html vendored

@ -1,22 +0,0 @@
<h3>About Flask</h3>
<p>
Flask is a micro web development framework for Python. You are currently
looking at the documentation of the development version.
</p>
<h3>Other Formats</h3>
<p>
You can download the documentation in other formats as well:
</p>
<ul>
<li><a href="http://flask.pocoo.org/docs/flask-docs.pdf">as PDF</a>
<li><a href="http://flask.pocoo.org/docs/flask-docs.epub">as ePub</a>
<li><a href="http://flask.pocoo.org/docs/flask-docs.mobi">as .mobi</a>
<li><a href="http://flask.pocoo.org/docs/flask-docs.zip">as zipped HTML</a>
</ul>
<h3>Useful Links</h3>
<ul>
<li><a href="http://flask.pocoo.org/">The Flask Website</a></li>
<li><a href="https://pypi.python.org/pypi/Flask">Flask @ PyPI</a></li>
<li><a href="https://github.com/pallets/flask">Flask @ GitHub</a></li>
<li><a href="https://github.com/pallets/flask/issues">Issue Tracker</a></li>
</ul>

3
docs/_templates/sidebarlogo.html vendored

@ -1,3 +0,0 @@
<p class="logo"><a href="{{ pathto(master_doc) }}">
<img class="logo" src="{{ pathto('_static/flask.png', 1) }}" alt="Logo"/>
</a></p>

2
docs/api.rst

@ -631,7 +631,7 @@ The following signals exist in Flask:
operations, including connecting. operations, including connecting.
.. _blinker: https://pypi.python.org/pypi/blinker .. _blinker: https://pypi.org/project/blinker/
.. _class-based-views: .. _class-based-views:

322
docs/conf.py

@ -1,285 +1,101 @@
# -*- coding: utf-8 -*- # -*- 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 __future__ import print_function
import datetime import inspect
import os import re
import sys
import time
import pkg_resources from pallets_sphinx_themes import DocVersion, ProjectLink, get_version
BUILD_DATE = datetime.datetime.utcfromtimestamp(int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))) # Project --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory, project = 'Flask'
# add these directories to sys.path here. If the directory is relative to the copyright = '2010 Pallets Team'
# documentation root, use os.path.abspath to make it absolute, like shown here. author = 'Pallets Team'
sys.path.append(os.path.dirname(__file__)) release, version = get_version('Flask')
# -- General configuration ----------------------------------------------------- # General --------------------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. master_doc = 'index'
#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 = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.intersphinx', 'sphinx.ext.intersphinx',
'flaskdocext' 'sphinxcontrib.log_cabinet',
] ]
try: intersphinx_mapping = {
__import__('sphinxcontrib.log_cabinet') 'python': ('https://docs.python.org/3/', None),
except ImportError: 'werkzeug': ('http://werkzeug.pocoo.org/docs/', None),
print('sphinxcontrib-log-cabinet is not installed.') 'click': ('http://click.pocoo.org/', None),
print('Changelog directives will not be re-organized.') 'jinja': ('http://jinja.pocoo.org/docs/', None),
else: 'itsdangerous': ('https://pythonhosted.org/itsdangerous', None),
extensions.append('sphinxcontrib.log_cabinet') 'sqlalchemy': ('https://docs.sqlalchemy.org/en/latest/', None),
'wtforms': ('https://wtforms.readthedocs.io/en/latest/', None),
# Add any paths that contain templates here, relative to this directory. 'blinker': ('https://pythonhosted.org/blinker/', None),
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'Flask'
copyright = u'2010 - {0}, Armin Ronacher'.format(BUILD_DATE.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
# "<project> v<release> 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']
# 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 # HTML -----------------------------------------------------------------
# typographically correct entities.
#html_use_smartypants = True
# 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/'),
],
'versions': [
DocVersion('dev', 'Development', 'unstable'),
DocVersion('1.0', 'Flask 1.0', 'stable'),
DocVersion('0.12', 'Flask 0.12'),
],
'canonical_url': 'http://flask.pocoo.org/docs/{}/'.format(version),
'carbon_ads_args': 'zoneid=1673&serve=C6AILKT&placement=pocooorg',
}
html_sidebars = { html_sidebars = {
'index': [ 'index': [
'sidebarintro.html', 'project.html',
'sourcelink.html', 'versions.html',
'searchbox.html' 'searchbox.html',
], ],
'**': [ '**': [
'sidebarlogo.html',
'localtoc.html', 'localtoc.html',
'relations.html', 'relations.html',
'sourcelink.html', 'versions.html',
'searchbox.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 # LaTeX ----------------------------------------------------------------
# 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 <link> 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 --------------------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [ 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_use_modindex = False
latex_elements = { latex_elements = {
'fontpkg': r'\usepackage{mathpazo}',
'papersize': 'a4paper', 'papersize': 'a4paper',
'pointsize': '12pt', 'pointsize': '12pt',
'preamble': r'\usepackage{flaskstyle}' 'fontpkg': r'\usepackage{mathpazo}',
'preamble': r'\usepackage{flaskstyle}',
} }
latex_use_parts = True latex_use_parts = True
latex_additional_files = ['flaskstyle.sty', 'logo.pdf'] latex_additional_files = ['flaskstyle.sty', 'logo.pdf']
# linkcheck ------------------------------------------------------------
# -- Options for Epub output --------------------------------------------------- linkcheck_anchors = False
# 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 an 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. # Local Extensions -----------------------------------------------------
#epub_tocdepth = 3
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),
}
html_theme_options = {
'touch_icon': 'touch-icon.png'
}
# unwrap decorators
def unwrap_decorators(): def unwrap_decorators():
import sphinx.util.inspect as inspect import sphinx.util.inspect as inspect
import functools import functools
@ -296,11 +112,21 @@ def unwrap_decorators():
return rv return rv
functools.update_wrapper = update_wrapper functools.update_wrapper = update_wrapper
unwrap_decorators() unwrap_decorators()
del unwrap_decorators del unwrap_decorators
def setup(app): _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): def cut_module_meta(app, what, name, obj, options, lines):
"""Remove metadata from autodoc output.""" """Remove metadata from autodoc output."""
if what != 'module': if what != 'module':
@ -311,11 +137,9 @@ def setup(app):
if not line.startswith((':copyright:', ':license:')) if not line.startswith((':copyright:', ':license:'))
] ]
app.connect('autodoc-process-docstring', cut_module_meta)
def github_link( def github_link(
name, rawtext, text, lineno, inliner, name, rawtext, text, lineno, inliner, options=None, content=None
options=None, content=None
): ):
app = inliner.document.settings.env.app app = inliner.document.settings.env.app
release = app.config.release release = app.config.release
@ -342,4 +166,8 @@ def setup(app):
node = reference(rawtext, words, refuri=url, **options) node = reference(rawtext, words, refuri=url, **options)
return [node], [] 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) app.add_role('gh', github_link)

2
docs/deploying/fastcgi.rst

@ -237,4 +237,4 @@ python path. Common problems are:
.. _nginx: https://nginx.org/ .. _nginx: https://nginx.org/
.. _lighttpd: https://www.lighttpd.net/ .. _lighttpd: https://www.lighttpd.net/
.. _cherokee: http://cherokee-project.com/ .. _cherokee: http://cherokee-project.com/
.. _flup: https://pypi.python.org/pypi/flup .. _flup: https://pypi.org/project/flup/

2
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 .. _mod_wsgi: https://github.com/GrahamDumpleton/mod_wsgi
.. _installation instructions: https://modwsgi.readthedocs.io/en/develop/installation.html .. _installation instructions: https://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: https://modwsgi.readthedocs.io/en/develop/index.html .. _mod_wsgi documentation: https://modwsgi.readthedocs.io/en/develop/index.html
Troubleshooting Troubleshooting

5
docs/extensiondev.rst

@ -328,8 +328,8 @@ extension to be approved you have to follow these guidelines:
6. Approved extensions must define all their dependencies in the 6. Approved extensions must define all their dependencies in the
:file:`setup.py` file unless a dependency cannot be met because it is not :file:`setup.py` file unless a dependency cannot be met because it is not
available on PyPI. available on PyPI.
7. The extension must have documentation that uses one of the two Flask 7. The documentation must use the ``flask`` theme from the `Official
themes for Sphinx documentation. Pallets Themes`_.
8. The setup.py description (and thus the PyPI description) has to 8. The setup.py description (and thus the PyPI description) has to
link to the documentation, website (if there is one) and there link to the documentation, website (if there is one) and there
must be a link to automatically install the development version must be a link to automatically install the development version
@ -342,3 +342,4 @@ extension to be approved you have to follow these guidelines:
.. _OAuth extension: https://pythonhosted.org/Flask-OAuth/ .. _OAuth extension: https://pythonhosted.org/Flask-OAuth/
.. _mailinglist: http://flask.pocoo.org/mailinglist/ .. _mailinglist: http://flask.pocoo.org/mailinglist/
.. _IRC channel: http://flask.pocoo.org/community/irc/ .. _IRC channel: http://flask.pocoo.org/community/irc/
.. _Official Pallets Themes: https://pypi.org/project/pallets-sphinx-themes/

2
docs/extensions.rst

@ -50,4 +50,4 @@ extension.
.. _Extension Registry: http://flask.pocoo.org/extensions/ .. _Extension Registry: http://flask.pocoo.org/extensions/
.. _pypi: https://pypi.python.org/pypi?:action=browse&c=585 .. _pypi: https://pypi.org/search/?c=Framework+%3A%3A+Flask

16
docs/flaskdocext.py

@ -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)

4
docs/index.rst

@ -5,13 +5,13 @@ Welcome to Flask
.. image:: _static/logo-full.png .. image:: _static/logo-full.png
:alt: Flask: web development, one drop at a time :alt: Flask: web development, one drop at a time
:class: floatingflask :align: right
Welcome to Flask's documentation. Get started with :ref:`installation` Welcome to Flask's documentation. Get started with :ref:`installation`
and then get an overview with the :ref:`quickstart`. There is also a and then get an overview with the :ref:`quickstart`. There is also a
more detailed :ref:`tutorial` that shows how to create a small but more detailed :ref:`tutorial` that shows how to create a small but
complete application with Flask. Common patterns are described in the complete application with Flask. Common patterns are described in the
:ref:`patterns` section. The rest of the docs desribe each component of :ref:`patterns` section. The rest of the docs describe each component of
Flask in detail, with a full reference in the :ref:`api` section. Flask in detail, with a full reference in the :ref:`api` section.
Flask depends on the `Jinja`_ template engine and the `Werkzeug`_ WSGI Flask depends on the `Jinja`_ template engine and the `Werkzeug`_ WSGI

2
docs/installation.rst

@ -27,7 +27,7 @@ These distributions will be installed automatically when installing Flask.
.. _Werkzeug: http://werkzeug.pocoo.org/ .. _Werkzeug: http://werkzeug.pocoo.org/
.. _Jinja: http://jinja.pocoo.org/ .. _Jinja: http://jinja.pocoo.org/
.. _MarkupSafe: https://pypi.python.org/pypi/MarkupSafe .. _MarkupSafe: https://pypi.org/project/MarkupSafe/
.. _ItsDangerous: https://pythonhosted.org/itsdangerous/ .. _ItsDangerous: https://pythonhosted.org/itsdangerous/
.. _Click: http://click.pocoo.org/ .. _Click: http://click.pocoo.org/

137
docs/make.bat

@ -1,139 +1,36 @@
@ECHO OFF @ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" ( if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build set SPHINXBUILD=sphinx-build
) )
set SOURCEDIR=.
set BUILDDIR=_build set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . set SPHINXPROJ=Flask
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
)
if "%1" == "" goto help if "%1" == "" goto help
if "%1" == "help" ( %SPHINXBUILD% >NUL 2>NUL
:help if errorlevel 9009 (
echo.Please use `make ^<target^>` where ^<target^> 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
echo. echo.
echo.Build finished; now you can process the pickle files. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
goto end 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.
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
echo. echo.
echo.Build finished; now you can process the JSON files. echo.If you don't have Sphinx installed, grab it from
goto end echo.http://sphinx-doc.org/
exit /b 1
) )
if "%1" == "htmlhelp" ( %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
%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 goto end
)
if "%1" == "qthelp" ( :help
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
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
)
:end :end
popd

2
docs/patterns/caching.rst

@ -27,7 +27,7 @@ cache that keeps the item stored in the memory of the Python interpreter::
cache = SimpleCache() cache = SimpleCache()
If you want to use memcached, make sure to have one of the memcache modules If you want to use memcached, make sure to have one of the memcache modules
supported (you get them from `PyPI <https://pypi.python.org/pypi>`_) and a supported (you get them from `PyPI <https://pypi.org/>`_) and a
memcached server running somewhere. This is how you connect to such an memcached server running somewhere. This is how you connect to such an
memcached server then:: memcached server then::

4
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. 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://pypi.python.org/pypi/setuptools .. _Setuptools: https://pypi.org/project/setuptools/

2
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. if you want to get started quickly.
You can download `Flask-SQLAlchemy`_ from `PyPI You can download `Flask-SQLAlchemy`_ from `PyPI
<https://pypi.python.org/pypi/Flask-SQLAlchemy>`_. <https://pypi.org/project/Flask-SQLAlchemy/>`_.
.. _Flask-SQLAlchemy: http://flask-sqlalchemy.pocoo.org/ .. _Flask-SQLAlchemy: http://flask-sqlalchemy.pocoo.org/

2
docs/patterns/wtforms.rst

@ -17,7 +17,7 @@ forms.
The `Flask-WTF`_ extension expands on this pattern and adds a The `Flask-WTF`_ extension expands on this pattern and adds a
few little helpers that make working with forms and Flask more few little helpers that make working with forms and Flask more
fun. You can get it from `PyPI fun. You can get it from `PyPI
<https://pypi.python.org/pypi/Flask-WTF>`_. <https://pypi.org/project/Flask-WTF/>`_.
.. _Flask-WTF: https://flask-wtf.readthedocs.io/en/stable/ .. _Flask-WTF: https://flask-wtf.readthedocs.io/en/stable/

2
docs/signals.rst

@ -187,4 +187,4 @@ Core Signals
Take a look at :ref:`core-signals-list` for a list of all builtin 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/

2
flask/cli.py

@ -243,7 +243,7 @@ def locate_app(script_info, module_name, app_name, raise_if_not_found=True):
) )
elif raise_if_not_found: elif raise_if_not_found:
raise NoAppException( raise NoAppException(
'Could not import "{name}"."'.format(name=module_name) 'Could not import "{name}".'.format(name=module_name)
) )
else: else:
return return

2
flask/helpers.py

@ -486,7 +486,7 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
The `attachment_filename` is preferred over `filename` for MIME-type The `attachment_filename` is preferred over `filename` for MIME-type
detection. detection.
.. versionchanged:: 0.13 .. versionchanged:: 1.0
UTF-8 filenames, as specified in `RFC 2231`_, are supported. UTF-8 filenames, as specified in `RFC 2231`_, are supported.
.. _RFC 2231: https://tools.ietf.org/html/rfc2231#section-4 .. _RFC 2231: https://tools.ietf.org/html/rfc2231#section-4

7
setup.py

@ -38,7 +38,14 @@ setup(
'coverage', 'coverage',
'tox', 'tox',
'sphinx', 'sphinx',
'pallets-sphinx-themes',
'sphinxcontrib-log-cabinet',
], ],
'docs': [
'sphinx',
'pallets-sphinx-themes',
'sphinxcontrib-log-cabinet',
]
}, },
classifiers=[ classifiers=[
'Development Status :: 5 - Production/Stable', 'Development Status :: 5 - Production/Stable',

10
tox.ini

@ -38,11 +38,17 @@ commands =
coverage run -p -m pytest tests examples coverage run -p -m pytest tests examples
[testenv:docs-html] [testenv:docs-html]
deps = sphinx deps =
sphinx
pallets-sphinx-themes
sphinxcontrib-log-cabinet
commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html
[testenv:docs-linkcheck] [testenv:docs-linkcheck]
deps = sphinx deps =
sphinx
pallets-sphinx-themes
sphinxcontrib-log-cabinet
commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs {envtmpdir}/linkcheck commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs {envtmpdir}/linkcheck
[testenv:coverage-report] [testenv:coverage-report]

Loading…
Cancel
Save