From 49a38ed9995c5fa8fd07fde732845cbc08e890b0 Mon Sep 17 00:00:00 2001 From: David Lord Date: Thu, 12 Apr 2018 22:54:11 -0700 Subject: [PATCH] use theme provided by pallets-sphinx-themes --- .gitignore | 1 + CHANGES.rst | 2 +- docs/.gitignore | 1 - docs/Makefile | 118 +-------- docs/_templates/sidebarintro.html | 22 -- docs/_templates/sidebarlogo.html | 3 - docs/api.rst | 2 +- docs/conf.py | 390 +++++++++--------------------- docs/deploying/fastcgi.rst | 2 +- docs/deploying/mod_wsgi.rst | 2 +- docs/extensiondev.rst | 5 +- docs/extensions.rst | 2 +- docs/flaskdocext.py | 16 -- docs/index.rst | 4 +- docs/installation.rst | 2 +- docs/make.bat | 175 +++----------- docs/patterns/caching.rst | 2 +- docs/patterns/distribute.rst | 4 +- docs/patterns/sqlalchemy.rst | 2 +- docs/patterns/wtforms.rst | 2 +- docs/signals.rst | 2 +- flask/cli.py | 2 +- flask/helpers.py | 2 +- setup.py | 7 + tox.ini | 10 +- 25 files changed, 190 insertions(+), 590 deletions(-) delete mode 100644 docs/.gitignore delete mode 100644 docs/_templates/sidebarintro.html delete mode 100644 docs/_templates/sidebarlogo.html delete mode 100644 docs/flaskdocext.py diff --git a/.gitignore b/.gitignore index 04b039bf..8a323555 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ _mailinglist .cache/ .pytest_cache/ .idea/ +docs/_build/ # Coverage reports htmlcov/ diff --git a/CHANGES.rst b/CHANGES.rst index 185dd4d6..11a5da81 100644 --- a/CHANGES.rst +++ b/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 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 c3cb2881..00000000 --- a/docs/_templates/sidebarintro.html +++ /dev/null @@ -1,22 +0,0 @@ -

About Flask

-

- Flask is a micro web development 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/api.rst b/docs/api.rst index f344478b..982c07ba 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -631,7 +631,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 a037476e..9721fbf0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 -# " 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'] - -# 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 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) diff --git a/docs/deploying/fastcgi.rst b/docs/deploying/fastcgi.rst index 46706033..3d57eb9b 100644 --- a/docs/deploying/fastcgi.rst +++ b/docs/deploying/fastcgi.rst @@ -237,4 +237,4 @@ python path. Common problems are: .. _nginx: https://nginx.org/ .. _lighttpd: https://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 ca694b7d..c9da6a2d 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: 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 Troubleshooting diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 677cc19a..f48fb46b 100644 --- a/docs/extensiondev.rst +++ b/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 :file:`setup.py` file unless a dependency cannot be met because it is not available on PyPI. -7. The extension must have documentation that uses one of the two Flask - themes for Sphinx documentation. +7. The documentation must use the ``flask`` theme from the `Official + Pallets Themes`_. 8. The setup.py description (and thus the PyPI description) has to link to the documentation, website (if there is one) and there 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/ .. _mailinglist: http://flask.pocoo.org/mailinglist/ .. _IRC channel: http://flask.pocoo.org/community/irc/ +.. _Official Pallets Themes: https://pypi.org/project/pallets-sphinx-themes/ diff --git a/docs/extensions.rst b/docs/extensions.rst index 54e2c3eb..92e8a5b2 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -50,4 +50,4 @@ extension. .. _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 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/index.rst b/docs/index.rst index 5e9f8426..64ed4e92 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,13 +5,13 @@ 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. Get started with :ref:`installation` 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 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 depends on the `Jinja`_ template engine and the `Werkzeug`_ WSGI diff --git a/docs/installation.rst b/docs/installation.rst index e32ec6c7..15b2f8f7 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -27,7 +27,7 @@ These distributions will be installed automatically when installing Flask. .. _Werkzeug: http://werkzeug.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/ .. _Click: http://click.pocoo.org/ diff --git a/docs/make.bat b/docs/make.bat index 3ad12879..5ca2df6d 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,139 +1,36 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -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 - 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\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 +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=Flask + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + 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.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/patterns/caching.rst b/docs/patterns/caching.rst index 4ca8ea42..fb96a559 100644 --- a/docs/patterns/caching.rst +++ b/docs/patterns/caching.rst @@ -27,7 +27,7 @@ cache that keeps the item stored in the memory of the Python interpreter:: cache = SimpleCache() If you want to use memcached, make sure to have one of the memcache modules -supported (you get them from `PyPI `_) and a +supported (you get them from `PyPI `_) and a memcached server running somewhere. This is how you connect to such an memcached server then:: diff --git a/docs/patterns/distribute.rst b/docs/patterns/distribute.rst index 0c7c8658..51a73528 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 -.. _Setuptools: https://pypi.python.org/pypi/setuptools +.. _pip: https://pypi.org/project/pip/ +.. _Setuptools: https://pypi.org/project/setuptools/ diff --git a/docs/patterns/sqlalchemy.rst b/docs/patterns/sqlalchemy.rst index 8785a6e2..831d54f0 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://flask-sqlalchemy.pocoo.org/ diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index 0e53de17..e3fe5723 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: https://flask-wtf.readthedocs.io/en/stable/ diff --git a/docs/signals.rst b/docs/signals.rst index 40041491..2cf3ce60 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/flask/cli.py b/flask/cli.py index 3e2823c7..c2edfdb0 100644 --- a/flask/cli.py +++ b/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: raise NoAppException( - 'Could not import "{name}"."'.format(name=module_name) + 'Could not import "{name}".'.format(name=module_name) ) else: return diff --git a/flask/helpers.py b/flask/helpers.py index 1b8e323b..88f2302a 100644 --- a/flask/helpers.py +++ b/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 detection. - .. versionchanged:: 0.13 + .. versionchanged:: 1.0 UTF-8 filenames, as specified in `RFC 2231`_, are supported. .. _RFC 2231: https://tools.ietf.org/html/rfc2231#section-4 diff --git a/setup.py b/setup.py index 4ad54766..26e531f1 100755 --- a/setup.py +++ b/setup.py @@ -38,7 +38,14 @@ setup( 'coverage', 'tox', 'sphinx', + 'pallets-sphinx-themes', + 'sphinxcontrib-log-cabinet', ], + 'docs': [ + 'sphinx', + 'pallets-sphinx-themes', + 'sphinxcontrib-log-cabinet', + ] }, classifiers=[ 'Development Status :: 5 - Production/Stable', diff --git a/tox.ini b/tox.ini index 5818fa89..03e53d90 100644 --- a/tox.ini +++ b/tox.ini @@ -38,11 +38,17 @@ commands = coverage run -p -m pytest tests examples [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 [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 [testenv:coverage-report]