|
|
|
|
@ -1,285 +1,101 @@
|
|
|
|
|
# -*- 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 |
|
|
|
|
|
|
|
|
|
import datetime |
|
|
|
|
import os |
|
|
|
|
import sys |
|
|
|
|
import time |
|
|
|
|
import inspect |
|
|
|
|
import re |
|
|
|
|
|
|
|
|
|
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, |
|
|
|
|
# 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.dirname(__file__)) |
|
|
|
|
project = 'Flask' |
|
|
|
|
copyright = '2010 Pallets Team' |
|
|
|
|
author = 'Pallets Team' |
|
|
|
|
release, version = get_version('Flask') |
|
|
|
|
|
|
|
|
|
# -- General configuration ----------------------------------------------------- |
|
|
|
|
# General -------------------------------------------------------------- |
|
|
|
|
|
|
|
|
|
# If your documentation needs a minimal Sphinx version, state it here. |
|
|
|
|
#needs_sphinx = '1.0' |
|
|
|
|
master_doc = 'index' |
|
|
|
|
|
|
|
|
|
# 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' |
|
|
|
|
'sphinxcontrib.log_cabinet', |
|
|
|
|
] |
|
|
|
|
|
|
|
|
|
try: |
|
|
|
|
__import__('sphinxcontrib.log_cabinet') |
|
|
|
|
except ImportError: |
|
|
|
|
print('sphinxcontrib-log-cabinet is not installed.') |
|
|
|
|
print('Changelog directives will not be re-organized.') |
|
|
|
|
else: |
|
|
|
|
extensions.append('sphinxcontrib.log_cabinet') |
|
|
|
|
|
|
|
|
|
# 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'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' |
|
|
|
|
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/'), |
|
|
|
|
], |
|
|
|
|
'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 = { |
|
|
|
|
'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 <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 -------------------------------------------------- |
|
|
|
|
# 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 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. |
|
|
|
|
#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), |
|
|
|
|
} |
|
|
|
|
linkcheck_anchors = False |
|
|
|
|
|
|
|
|
|
html_theme_options = { |
|
|
|
|
'touch_icon': 'touch-icon.png' |
|
|
|
|
} |
|
|
|
|
# Local Extensions ----------------------------------------------------- |
|
|
|
|
|
|
|
|
|
# unwrap decorators |
|
|
|
|
def unwrap_decorators(): |
|
|
|
|
import sphinx.util.inspect as inspect |
|
|
|
|
import functools |
|
|
|
|
@ -296,50 +112,62 @@ def unwrap_decorators():
|
|
|
|
|
return rv |
|
|
|
|
functools.update_wrapper = update_wrapper |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
unwrap_decorators() |
|
|
|
|
del unwrap_decorators |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def setup(app): |
|
|
|
|
def cut_module_meta(app, what, name, obj, options, lines): |
|
|
|
|
"""Remove metadata from autodoc output.""" |
|
|
|
|
if what != 'module': |
|
|
|
|
return |
|
|
|
|
_internal_mark_re = re.compile(r'^\s*:internal:\s*$(?m)', re.M) |
|
|
|
|
|
|
|
|
|
lines[:] = [ |
|
|
|
|
line for line in lines |
|
|
|
|
if not line.startswith((':copyright:', ':license:')) |
|
|
|
|
] |
|
|
|
|
|
|
|
|
|
app.connect('autodoc-process-docstring', cut_module_meta) |
|
|
|
|
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 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 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) |
|
|
|
|
|
David Lord
7 years ago