diff --git a/docs/conf.py b/docs/conf.py index 04172441..a6bf4e5b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,168 +1,99 @@ # -*- coding: utf-8 -*- from __future__ import print_function -import inspect -import re - -from pallets_sphinx_themes import DocVersion, ProjectLink, get_version +from pallets_sphinx_themes import ProjectLink, get_version # Project -------------------------------------------------------------- -project = 'Flask' -copyright = '2010 Pallets Team' -author = 'Pallets Team' -release, version = get_version('Flask') +project = "Flask" +copyright = "2010 Pallets Team" +author = "Pallets Team" +release, version = get_version("Flask") # General -------------------------------------------------------------- -master_doc = 'index' - +master_doc = "index" extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinxcontrib.log_cabinet', + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinxcontrib.log_cabinet", + "pallets_sphinx_themes", ] - 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), + "python": ("https://docs.python.org/3/", None), + "werkzeug": ("http://werkzeug.pocoo.org/docs/", None), + "click": ("https://click.palletsprojects.com/", None), + "jinja": ("http://jinja.pocoo.org/docs/", None), + "itsdangerous": ("https://itsdangerous.palletsprojects.com/", None), + "sqlalchemy": ("https://docs.sqlalchemy.org/", None), + "wtforms": ("https://wtforms.readthedocs.io/en/stable/", None), + "blinker": ("https://pythonhosted.org/blinker/", None), } # HTML ----------------------------------------------------------------- -html_theme = 'flask' +html_theme = "flask" +html_theme_options = {"index_sidebar_logo": False} html_context = { - 'project_links': [ - ProjectLink('Donate to Pallets', 'https://psfmember.org/civicrm/contribute/transact?reset=1&id=20'), - 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': [ - 'project.html', - 'versions.html', - 'carbon_ads.html', - 'searchbox.html', - ], - '**': [ - 'localtoc.html', - 'relations.html', - 'versions.html', - 'carbon_ads.html', - 'searchbox.html', + "project_links": [ + ProjectLink("Donate to Pallets", "https://palletsprojects.com/donate"), + 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/"), ] } -html_static_path = ['_static'] -html_favicon = '_static/flask-favicon.ico' -html_logo = '_static/flask.png' -html_additional_pages = { - '404': '404.html', +html_sidebars = { + "index": ["project.html", "localtoc.html", "searchbox.html"], + "**": ["localtoc.html", "relations.html", "searchbox.html"], } +singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]} +html_static_path = ["_static"] +html_favicon = "_static/flask-favicon.ico" +html_logo = "_static/flask.png" +html_title = "Flask Documentation ({})".format(version) html_show_sourcelink = False # LaTeX ---------------------------------------------------------------- latex_documents = [ - (master_doc, 'Flask.tex', 'Flask Documentation', 'Pallets Team', 'manual'), + (master_doc, "Flask.tex", "Flask Documentation", "Pallets Team", "manual") ] latex_use_modindex = False latex_elements = { - 'papersize': 'a4paper', - 'pointsize': '12pt', - 'fontpkg': r'\usepackage{mathpazo}', - 'preamble': r'\usepackage{flaskstyle}', + "papersize": "a4paper", + "pointsize": "12pt", + "fontpkg": r"\usepackage{mathpazo}", + "preamble": r"\usepackage{flaskstyle}", } latex_use_parts = True -latex_additional_files = ['flaskstyle.sty', 'logo.pdf'] - -# linkcheck ------------------------------------------------------------ - -linkcheck_anchors = False +latex_additional_files = ["flaskstyle.sty", "logo.pdf"] # Local Extensions ----------------------------------------------------- -def unwrap_decorators(): - import sphinx.util.inspect as inspect - import functools - old_getargspec = inspect.getargspec - def getargspec(x): - return old_getargspec(getattr(x, '_original_function', x)) - inspect.getargspec = getargspec - - old_update_wrapper = functools.update_wrapper - def update_wrapper(wrapper, wrapped, *a, **kw): - rv = old_update_wrapper(wrapper, wrapped, *a, **kw) - rv._original_function = wrapped - 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 -): +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/' + base_url = "https://github.com/pallets/flask/tree/" - if text.endswith('>'): - words, text = text[:-1].rsplit('<', 1) + 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) + if release.endswith("dev"): + url = "{0}master/{1}".format(base_url, text) else: - url = '{0}{1}/{2}'.format(base_url, release, text) + 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) @@ -170,6 +101,4 @@ def github_link( 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) diff --git a/docs/index.rst b/docs/index.rst index 64ed4e92..52acff41 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,12 @@ -:orphan: +.. rst-class:: hide-header Welcome to Flask ================ .. image:: _static/logo-full.png :alt: Flask: web development, one drop at a time - :align: right + :align: center + :target: https://palletsprojects.com/p/flask/ Welcome to Flask's documentation. Get started with :ref:`installation` and then get an overview with the :ref:`quickstart`. There is also a diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..e667deaa --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +Sphinx~=1.8.0 +Pallets-Sphinx-Themes~=1.1.0 +sphinxcontrib-log-cabinet~=1.0.0 diff --git a/tox.ini b/tox.ini index 546b9279..cdeee4c3 100644 --- a/tox.ini +++ b/tox.ini @@ -39,18 +39,9 @@ commands = [testenv:docs-html] deps = - sphinx - pallets-sphinx-themes - sphinxcontrib-log-cabinet + -r docs/requirements.txt commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html -[testenv:docs-linkcheck] -deps = - sphinx - pallets-sphinx-themes - sphinxcontrib-log-cabinet -commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs {envtmpdir}/linkcheck - [testenv:coverage-report] deps = coverage skip_install = true