From 5c6f580d9a9eb29ea7316e83cb083d6f9500f37b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 04:14:52 -0800 Subject: Rename to README.rst for better rendering on GitHub --- README | 11 ----------- README.rst | 11 +++++++++++ setup.py | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) delete mode 100644 README create mode 100644 README.rst diff --git a/README b/README deleted file mode 100644 index 291a026..0000000 --- a/README +++ /dev/null @@ -1,11 +0,0 @@ -This tool provides code to load WSGI applications and servers from -URIs; these URIs can refer to Python Eggs for INI-style configuration -files. `Paste Script `_ provides -commands to serve applications based on this configuration file. - -The latest version is available in a `Mercurial repository -`_ (or a `tarball -`_). - -For the latest changes see the `news file -`_. \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..291a026 --- /dev/null +++ b/README.rst @@ -0,0 +1,11 @@ +This tool provides code to load WSGI applications and servers from +URIs; these URIs can refer to Python Eggs for INI-style configuration +files. `Paste Script `_ provides +commands to serve applications based on this configuration file. + +The latest version is available in a `Mercurial repository +`_ (or a `tarball +`_). + +For the latest changes see the `news file +`_. \ No newline at end of file diff --git a/setup.py b/setup.py index 79f9d70..b5d6be4 100644 --- a/setup.py +++ b/setup.py @@ -3,7 +3,7 @@ import os from setuptools import setup, find_packages here = os.path.dirname(__file__) -readme_path = os.path.join(here, 'README') +readme_path = os.path.join(here, 'README.rst.rst') readme = open(readme_path).read() -- cgit v1.2.1 From 98cabc41ecf67c67123af7e08d4abc96839ae5d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 04:36:14 -0800 Subject: Update URLs in README and setup.py - See #2 and #4 --- README.rst | 12 ++++++------ setup.py | 9 +++++++-- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 291a026..0524978 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,11 @@ This tool provides code to load WSGI applications and servers from -URIs; these URIs can refer to Python Eggs for INI-style configuration -files. `Paste Script `_ provides +URIs. These URIs can refer to Python eggs for INI-style configuration +files. `Paste Script `_ provides commands to serve applications based on this configuration file. -The latest version is available in a `Mercurial repository -`_ (or a `tarball -`_). +The latest version is available on `GitHub +`_ (or download a wheel or tarball from +`PyPI `_). For the latest changes see the `news file -`_. \ No newline at end of file +`_. diff --git a/setup.py b/setup.py index b5d6be4..5a8d019 100644 --- a/setup.py +++ b/setup.py @@ -3,7 +3,7 @@ import os from setuptools import setup, find_packages here = os.path.dirname(__file__) -readme_path = os.path.join(here, 'README.rst.rst') +readme_path = os.path.join(here, "README.rst") readme = open(readme_path).read() @@ -36,7 +36,12 @@ setup( author_email='ianb@colorstudy.com', maintainer='Alex Gronholm', maintainer_email='alex.gronholm@nextday.fi', - url='http://pythonpaste.org/deploy/', + url="https://pylonsproject.org/", + project_urls={ + "Documentation": "https://docs.pylonsproject.org/projects/pastedeploy/en/latest/", + "Changelog": "https://docs.pylonsproject.org/projects/pastedeploy/en/latest/news.html", + "Issue Tracker": "https://github.com/Pylons/pastedeploy/issues", + }, license='MIT', namespace_packages=['paste'], packages=find_packages(exclude=['tests']), -- cgit v1.2.1 From aca1082bfc23269858da93dba2f93d700f656a86 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:07:49 -0800 Subject: Add docs_extra to setup.py --- setup.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/setup.py b/setup.py index 5a8d019..cf47dad 100644 --- a/setup.py +++ b/setup.py @@ -6,6 +6,10 @@ here = os.path.dirname(__file__) readme_path = os.path.join(here, "README.rst") readme = open(readme_path).read() +docs_extras = [ + 'Sphinx >= 1.7.5', # Read The Docs minimum version + 'pylons-sphinx-themes', +] setup( name='PasteDeploy', @@ -52,6 +56,7 @@ setup( extras_require={ 'Config': [], 'Paste': ['Paste'], + 'docs': docs_extras, }, entry_points=""" [paste.filter_app_factory] -- cgit v1.2.1 From 546913f94d6d00289f3be8fd66cb678b4f3659cc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:27:51 -0800 Subject: Use pylons-sphinx-themes for pylons --- docs/conf.py | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index af16cab..17bdf1c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,6 +12,7 @@ # serve to show the default value. import sys +import pylons_sphinx_themes # If your extensions are in another directory, add it here. #sys.path.append('some/directory') @@ -71,10 +72,16 @@ pygments_style = 'sphinx' # Options for HTML output # ----------------------- +html_theme = 'pylons' +html_theme_path = pylons_sphinx_themes.get_html_themes_path() +html_theme_options = dict( + canonical_url='https://docs.pylonsproject.org/projects/pastedeploy/en/latest/' +) + # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. -html_style = 'default.css' +# html_style = 'default.css' # 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, @@ -85,15 +92,21 @@ html_static_path = ['_static'] # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True +# Do not use smart quotes. +smartquotes = False # Content template for the index page. #html_index = '' # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# Control display of sidebars +html_sidebars = { '**': [ + 'localtoc.html', + 'ethicalads.html', + 'relations.html', + 'sourcelink.html', + 'searchbox.html', +] } # Additional templates that should be rendered to pages, maps page names to # template names. -- cgit v1.2.1 From a8b59275dd6dd4a8369478a6bd5e56c5b62927d5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:28:13 -0800 Subject: Fix broken link to get initial html docs built --- docs/index.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index c085d27..ae0bdbb 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -67,7 +67,7 @@ Installation First make sure you have either `setuptools `_ or its modern replacement -`distribute `_ installed. +`distribute `_ installed. For Python 3.x you need distribute as setuptools does not work on it. Then you can install Paste Deployment using `pip @@ -451,7 +451,7 @@ other with the attributes ``.local_conf`` and ``.global_conf``. `Python Eggs `_ are a distribution and installation format produced by `setuptools `_ and -`distribute `_ that adds metadata to a +`distribute `_ that adds metadata to a normal Python package (among other things). You don't need to understand a whole lot about Eggs to use them. If -- cgit v1.2.1 From 18de398757b30a025acf6d1586568702980929d8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:29:13 -0800 Subject: Move license.txt to root of repo in hopes that GitHub will find it --- docs/license.txt | 20 -------------------- license.txt | 20 ++++++++++++++++++++ 2 files changed, 20 insertions(+), 20 deletions(-) delete mode 100644 docs/license.txt create mode 100644 license.txt diff --git a/docs/license.txt b/docs/license.txt deleted file mode 100644 index c810dec..0000000 --- a/docs/license.txt +++ /dev/null @@ -1,20 +0,0 @@ -Copyright (c) 2006-2007 Ian Bicking and Contributors - -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/license.txt b/license.txt new file mode 100644 index 0000000..c810dec --- /dev/null +++ b/license.txt @@ -0,0 +1,20 @@ +Copyright (c) 2006-2007 Ian Bicking and Contributors + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -- cgit v1.2.1 From 4cdea7782c219e40c8ad28d05b3097b68624e58e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:34:17 -0800 Subject: Remove obsolete links from navigation --- docs/_static/paste.css | 15 --------------- docs/_templates/layout.html | 20 -------------------- 2 files changed, 35 deletions(-) delete mode 100644 docs/_static/paste.css delete mode 100644 docs/_templates/layout.html diff --git a/docs/_static/paste.css b/docs/_static/paste.css deleted file mode 100644 index 6705e5d..0000000 --- a/docs/_static/paste.css +++ /dev/null @@ -1,15 +0,0 @@ -a.invisible-link { - color: #fff; - text-decoration: none; -} - -a.invisible-link:visited { - color: #fff; - text-decoration: none; -} - -a.invisible:link { - color: #fff; - text-decoration: none; -} - diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index a6d2a97..0000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,20 +0,0 @@ -{% extends "!layout.html" %} - -{% block extrahead %} -{{ super() }} - -{% endblock %} - -{% block sidebartoc %} -

Python Paste

- - - -{{ super() }} -{% endblock %} -- cgit v1.2.1 From e4591d8c92a1267dbfb654f8fc9e6d37b9b77449 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 05:35:56 -0800 Subject: Remove license from docs --- docs/index.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.txt b/docs/index.txt index ae0bdbb..e6c4351 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,7 +14,6 @@ Documents: modules/loadwsgi modules/config modules/converters - license .. comment: The names used in sections should be more concrete, and it should -- cgit v1.2.1 From 70e149d7e923d0fdaea66906914acb1685badcb5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 26 Nov 2018 04:26:16 -0800 Subject: Update link to pastescript in README.rst --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 0524978..7e4dcac 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ This tool provides code to load WSGI applications and servers from URIs. These URIs can refer to Python eggs for INI-style configuration -files. `Paste Script `_ provides +files. `Paste Script `_ provides commands to serve applications based on this configuration file. The latest version is available on `GitHub -- cgit v1.2.1 From 6c0b9e59ae252543c46011368df56f46c9d935a4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:21:38 -0800 Subject: Synch with master --- setup.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.py b/setup.py index cf47dad..b421563 100644 --- a/setup.py +++ b/setup.py @@ -51,8 +51,8 @@ setup( packages=find_packages(exclude=['tests']), include_package_data=True, zip_safe=False, - test_suite='nose.collector', - tests_require=['nose>=0.11'], + setup_requires=['pytest-runner'], + tests_require=['pytest'], extras_require={ 'Config': [], 'Paste': ['Paste'], -- cgit v1.2.1 From e818929db195c8818502e60bae6fdbd09cb784c6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:21:46 -0800 Subject: proper spacing --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index b421563..623b847 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ readme_path = os.path.join(here, "README.rst") readme = open(readme_path).read() docs_extras = [ - 'Sphinx >= 1.7.5', # Read The Docs minimum version + 'Sphinx >= 1.7.5', # Read The Docs minimum version 'pylons-sphinx-themes', ] -- cgit v1.2.1 From a38ff6e5b1c8e9cf072dcfbc0eb1c6b2479baff5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:31:31 -0800 Subject: Comment out obsolete static path --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 17bdf1c..fc55a91 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,7 +86,7 @@ html_theme_options = dict( # 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'] +# html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -- cgit v1.2.1 From e8d04ccaa3fe9f09d50e20fd47e0c26773819c86 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:32:07 -0800 Subject: Add docs environment to tox. Build via `tox -e docs`. Closes #9 --- tox.ini | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 42469da..55e85c9 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,6 @@ [tox] -envlist = py27, py34, py35, py36, py37, pypy, pypy3 +envlist = py27, py34, py35, py36, py37, pypy, pypy3, + docs [testenv] usedevelop = True @@ -10,3 +11,12 @@ deps = pytest-cov commands = py.test {posargs} + +[testenv:docs] +# pin to 3.5 to match what RTD uses +basepython = python3.5 +whitelist_externals = make +commands = + make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E" +extras = + docs -- cgit v1.2.1 From 480661a406fa1d05c9121c4e6f38fbf92a7cd0e4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 04:14:52 -0800 Subject: Rename to README.rst for better rendering on GitHub --- README.rst | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 README.rst diff --git a/README.rst b/README.rst deleted file mode 100644 index 7e4dcac..0000000 --- a/README.rst +++ /dev/null @@ -1,11 +0,0 @@ -This tool provides code to load WSGI applications and servers from -URIs. These URIs can refer to Python eggs for INI-style configuration -files. `Paste Script `_ provides -commands to serve applications based on this configuration file. - -The latest version is available on `GitHub -`_ (or download a wheel or tarball from -`PyPI `_). - -For the latest changes see the `news file -`_. -- cgit v1.2.1 From ef9e4e59c2bbc4e11940bd08d9f84bb56fd5c29a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 04:36:14 -0800 Subject: Update URLs in README and setup.py - See #2 and #4 --- README.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..0524978 --- /dev/null +++ b/README.rst @@ -0,0 +1,11 @@ +This tool provides code to load WSGI applications and servers from +URIs. These URIs can refer to Python eggs for INI-style configuration +files. `Paste Script `_ provides +commands to serve applications based on this configuration file. + +The latest version is available on `GitHub +`_ (or download a wheel or tarball from +`PyPI `_). + +For the latest changes see the `news file +`_. -- cgit v1.2.1 From a6c6a7e8e545dc9e80d5d92b47724abca79dab72 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 26 Nov 2018 04:26:16 -0800 Subject: Update link to pastescript in README.rst --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 0524978..7e4dcac 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ This tool provides code to load WSGI applications and servers from URIs. These URIs can refer to Python eggs for INI-style configuration -files. `Paste Script `_ provides +files. `Paste Script `_ provides commands to serve applications based on this configuration file. The latest version is available on `GitHub -- cgit v1.2.1 From c3f314b7c26455abe20c651cb1ea3b27d3892e7b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:21:46 -0800 Subject: proper spacing --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index b421563..623b847 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ readme_path = os.path.join(here, "README.rst") readme = open(readme_path).read() docs_extras = [ - 'Sphinx >= 1.7.5', # Read The Docs minimum version + 'Sphinx >= 1.7.5', # Read The Docs minimum version 'pylons-sphinx-themes', ] -- cgit v1.2.1 From 1d851bf3fb50d8d1e34e6b146d7395d9013ed4bb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:31:31 -0800 Subject: Comment out obsolete static path --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 17bdf1c..fc55a91 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,7 +86,7 @@ html_theme_options = dict( # 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'] +# html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -- cgit v1.2.1 From 3323250a1363f48688803a34886fb984a89b4ad0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:32:07 -0800 Subject: Add docs environment to tox. Build via `tox -e docs`. Closes #9 --- tox.ini | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 9800db2..7819491 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,6 @@ [tox] -envlist = py27, py34, py35, py36, py37, pypy, pypy3 +envlist = py27, py34, py35, py36, py37, pypy, pypy3, + docs [testenv] deps = @@ -9,3 +10,12 @@ deps = pytest-cov commands = py.test --cov=paste/deploy --cov-report=xml --cov-report=html --cov-report=term-missing {posargs} + +[testenv:docs] +# pin to 3.5 to match what RTD uses +basepython = python3.5 +whitelist_externals = make +commands = + make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E" +extras = + docs -- cgit v1.2.1 From 210752708a193a7b61264aa853057bbc32db34e1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:33:52 -0800 Subject: Add Makefile to PR so tox can build docs --- docs/Makefile | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..91f36ae --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,107 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = sphinx-build +PAPER = +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 text web pickle htmlhelp latex latexpdf xelatexpdf changes linkcheck epub doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " text to make text files" + @echo " pickle to make pickle files (usable by e.g. sphinx-web)" + @echo " htmlhelp to make HTML files and a HTML help project" + @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 " xelatexpdf to make LaTeX files and run them through xelatex" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " epub to make an epub" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +xelatexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through xelatex..." + $(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf + @echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex." + +html: + mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +text: + mkdir -p $(BUILDDIR)/text $(BUILDDIR)/doctrees + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/text." + +pickle: + mkdir -p $(BUILDDIR)/pickle $(BUILDDIR)/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files or run" + @echo " sphinx-web $(BUILDDIR)/pickle" + @echo "to start the sphinx-web server." + +web: pickle + +htmlhelp: + mkdir -p $(BUILDDIR)/htmlhelp $(BUILDDIR)/doctrees + $(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." + +latex: + mkdir -p $(BUILDDIR)/latex $(BUILDDIR)/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + cp _static/*.png $(BUILDDIR)/latex + ./convert_images.sh + cp _static/latex-warning.png $(BUILDDIR)/latex + cp _static/latex-note.png $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make xelatexpdf' to build a PDF file from them." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF file is in $(BUILDDIR)/latex." + +changes: + mkdir -p $(BUILDDIR)/changes $(BUILDDIR)/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + mkdir -p $(BUILDDIR)/linkcheck $(BUILDDIR)/doctrees + $(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." + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." -- cgit v1.2.1 From 5312f2327fc8150133596b54307f02929b6759ff Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 03:44:55 -0800 Subject: Add rtd.txt to install pylons-sphinx-themes package --- rtd.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 rtd.txt diff --git a/rtd.txt b/rtd.txt new file mode 100644 index 0000000..142b6ca --- /dev/null +++ b/rtd.txt @@ -0,0 +1 @@ +-e .[docs] -- cgit v1.2.1 From 49fb53828e711fdff3f3b60c5355f64847ddb9cc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:01:36 -0800 Subject: Use .rst for extension for better rendering on GitHub --- docs/conf.py | 2 +- docs/index.rst | 671 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.txt | 671 --------------------------------------------------------- docs/news.rst | 179 +++++++++++++++ docs/news.txt | 179 --------------- 5 files changed, 851 insertions(+), 851 deletions(-) create mode 100644 docs/index.rst delete mode 100644 docs/index.txt create mode 100644 docs/news.rst delete mode 100644 docs/news.txt diff --git a/docs/conf.py b/docs/conf.py index 17bdf1c..c2c3191 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,7 @@ extensions = ['sphinx.ext.autodoc'] templates_path = ['_templates'] # The suffix of source filenames. -source_suffix = '.txt' +source_suffix = '.rst' # The master toctree document. master_doc = 'index' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..e6c4351 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,671 @@ +Paste Deployment +================ + +:author: Ian Bicking + +.. contents:: + +Documents: + +.. toctree:: + :maxdepth: 1 + + news + modules/loadwsgi + modules/config + modules/converters + +.. comment: + The names used in sections should be more concrete, and it should + be clearer that they are just arbitrary names. + +Introduction +------------ + +Paste Deployment is a system for finding and configuring WSGI +applications and servers. For WSGI application consumers it provides +a single, simple function (``loadapp``) for loading a WSGI application +from a configuration file or a Python Egg. For WSGI application +providers it only asks for a single, simple entry point to your +application, so that application users don't need to be exposed to the +implementation details of your application. + +The result is something a system administrator can install and manage +without knowing any Python, or the details of the WSGI application or +its container. + +Paste Deployment currently does not require other parts of `Paste +`_, and is distributed as a separate package. + +To see updates that have been made to Paste Deploy see the `news file +`_. + +Paste Deploy is released under the `MIT license +`_. + +Status +------ + +Paste Deploy has passed version 1.0. Paste Deploy is an actively +maintained project. As of 1.0, we'll make a strong effort to maintain +backward compatibility (this actually started happening long before +1.0, but now it is explicit). This will include deprecation warnings +when necessary. Major changes will take place under new functions or +with new entry points. + +Note that the most key aspect of Paste Deploy is the entry points it +defines (such as ``paste.app_factory``). Paste Deploy is not the only +consumer of these entry points, and many extensions can best take +place by utilizing the entry points instead of using Paste Deploy +directly. The entry points will not change; if changes are necessary, +new entry points will be defined. + +Installation +------------ + +First make sure you have either +`setuptools `_ or its +modern replacement +`distribute `_ installed. +For Python 3.x you need distribute as setuptools does not work on it. + +Then you can install Paste Deployment using `pip +`_ by running:: + + $ sudo pip install PasteDeploy + +If you want to track development, do:: + + $ hg clone http://bitbucket.org/ianb/pastedeploy + $ cd pastedeploy + $ sudo python setup.py develop + +This will install the package globally, but will load the files in the +checkout. You can also simply install ``PasteDeploy==dev``. + +For downloads and other information see the `Cheese Shop PasteDeploy +page `_. + +A complimentary package is `Paste Script `_. To install +that, use ``pip install PasteScript`` (or ``pip install +PasteScript==dev``). + +From the User Perspective +------------------------- + +In the following sections, the Python API for using Paste Deploy is +given. This isn't what users will be using (but it is useful for +Python developers and useful for setting up tests fixtures). + +The primary interaction with Paste Deploy is through its configuration +files. The primary thing you want to do with a configuration file is +serve it. To learn about serving configuration files, see `the +``paster serve`` command +`_. + +The Config File +~~~~~~~~~~~~~~~ + +A config file has different sections. The only sections Paste Deploy +cares about have prefixes, like ``app:main`` or ``filter:errors`` -- +the part after the ``:`` is the "name" of the section, and the part +before gives the "type". Other sections are ignored. + +The format is a simple `INI format +`_: ``name = value``. You can +extend the value by indenting subsequent lines. ``#`` is a comment. + +Typically you have one or two sections, named "main": an application +section (``[app:main]``) and a server section (``[server:main]``). +``[composite:...]`` signifies something that dispatches to multiple +applications (example below). + +Here's a typical configuration file that also shows off mounting +multiple applications using `paste.urlmap +`_:: + + [composite:main] + use = egg:Paste#urlmap + / = home + /blog = blog + /wiki = wiki + /cms = config:cms.ini + + [app:home] + use = egg:Paste#static + document_root = %(here)s/htdocs + + [filter-app:blog] + use = egg:Authentication#auth + next = blogapp + roles = admin + htpasswd = /home/me/users.htpasswd + + [app:blogapp] + use = egg:BlogApp + database = sqlite:/home/me/blog.db + + [app:wiki] + use = call:mywiki.main:application + database = sqlite:/home/me/wiki.db + +I'll explain each section in detail now:: + + [composite:main] + use = egg:Paste#urlmap + / = home + /blog = blog + /cms = config:cms.ini + +That this is a ``composite`` section means it dispatches the request +to other applications. ``use = egg:Paste#urlmap`` means to use the +composite application named ``urlmap`` from the ``Paste`` package. +``urlmap`` is a particularly common composite application -- it uses a +path prefix to map your request to another application. These are +the applications like "home", "blog", "wiki" and "config:cms.ini". The last +one just refers to another file ``cms.ini`` in the same directory. + +Next up:: + + [app:home] + use = egg:Paste#static + document_root = %(here)s/htdocs + +``egg:Paste#static`` is another simple application, in this case it +just serves up non-dynamic files. It takes one bit of configuration: +``document_root``. You can use variable substitution, which will pull +variables from the section ``[DEFAULT]`` (case sensitive!) with +markers like ``%(var_name)s``. The special variable ``%(here)s`` is +the directory containing the configuration file; you should use that +in lieu of relative filenames (which depend on the current directory, +which can change depending how the server is run). + +Then:: + + [filter-app:blog] + use = egg:Authentication#auth + next = blogapp + roles = admin + htpasswd = /home/me/users.htpasswd + + [app:blogapp] + use = egg:BlogApp + database = sqlite:/home/me/blog.db + +The ``[filter-app:blog]`` section means that you want an application +with a filter applied. The application being filtered is indicated +with ``next`` (which refers to the next section). The +``egg:Authentication#auth`` filter doesn't actually exist, but one +could imagine it logs people in and checks permissions. + +That last section is just a reference to an application that you +probably installed with ``pip install BlogApp``, and one bit of +configuration you passed to it (``database``). + +Lastly:: + + [app:wiki] + use = call:mywiki.main:application + database = sqlite:/home/me/wiki.db + +This section is similar to the previous one, with one important difference. +Instead of an entry point in an egg, it refers directly to the ``application`` +variable in the ``mywiki.main`` module. The reference consist of two parts, +separated by a colon. The left part is the full name of the module and the +right part is the path to the variable, as a Python expression relative to the +containing module. + +So, that's most of the features you'll use. + +Basic Usage +----------- + +The basic way you'll use Paste Deployment is to load `WSGI +`_ applications. Many +Python frameworks now support WSGI, so applications written for these +frameworks should be usable. + +The primary function is ``paste.deploy.loadapp``. This loads an +application given a URI. You can use it like:: + + from paste.deploy import loadapp + wsgi_app = loadapp('config:/path/to/config.ini') + +There's two URI formats currently supported: ``config:`` and ``egg:``. + +``config:`` URIs +---------------- + +URIs that being with ``config:`` refer to configuration files. These +filenames can be relative if you pass the ``relative_to`` keyword +argument to ``loadapp()``. + +.. note:: + + Filenames are never considered relative to the current working + directory, as that is a unpredictable location. Generally when + a URI has a context it will be seen as relative to that context; + for example, if you have a ``config:`` URI inside another + configuration file, the path is considered relative to the + directory that contains that configuration file. + +Config Format +~~~~~~~~~~~~~ + +Configuration files are in the INI format. This is a simple format +that looks like:: + + [section_name] + key = value + another key = a long value + that extends over multiple lines + +All values are strings (no quoting is necessary). The keys and +section names are case-sensitive, and may contain punctuation and +spaces (though both keys and values are stripped of leading and +trailing whitespace). Lines can be continued with leading whitespace. + +Lines beginning with ``#`` (preferred) or ``;`` are considered +comments. + +Applications +~~~~~~~~~~~~ + +You can define multiple applications in a single file; each +application goes in its own section. Even if you have just one +application, you must put it in a section. + +Each section name defining an application should be prefixed with +``app:``. The "main" section (when just defining one application) +would go in ``[app:main]`` or just ``[app]``. + +There's two ways to indicate the Python code for the application. The +first is to refer to another URI or name:: + + [app:myapp] + use = config:another_config_file.ini#app_name + + # or any URI: + [app:myotherapp] + use = egg:MyApp + + # or a callable from a module: + [app:mythirdapp] + use = call:my.project:myapplication + + # or even another section: + [app:mylastapp] + use = myotherapp + +It would seem at first that this was pointless; just a way to point to +another location. However, in addition to loading the application +from that location, you can also add or change the configuration. + +The other way to define an application is to point exactly to some +Python code:: + + [app:myapp] + paste.app_factory = myapp.modulename:app_factory + +You must give an explicit *protocol* (in this case +``paste.app_factory``), and the value is something to import. In +this case the module ``myapp.modulename`` is loaded, and the +``app_factory`` object retrieved from it. + +See `Defining Factories`_ for more about the protocols. + +Configuration +~~~~~~~~~~~~~ + +Configuration is done through keys besides ``use`` (or the protocol +names). Any other keys found in the section will be passed as keyword +arguments to the factory. This might look like:: + + [app:blog] + use = egg:MyBlog + database = mysql://localhost/blogdb + blogname = This Is My Blog! + +You can override these in other sections, like:: + + [app:otherblog] + use = blog + blogname = The other face of my blog + +This way some settings could be defined in a generic configuration +file (if you have ``use = config:other_config_file``) or you can +publish multiple (more specialized) applications just by adding a +section. + +Global Configuration +~~~~~~~~~~~~~~~~~~~~ + +Often many applications share the same configuration. While you can +do that a bit by using other config sections and overriding values, +often you want that done for a bunch of disparate configuration +values. And typically applications can't take "extra" configuration +parameters; with global configuration you do something equivalent to +"if this application wants to know the admin email, this is it". + +Applications are passed the global configuration separately, so they +must specifically pull values out of it; typically the global +configuration serves as the basis for defaults when no local +configuration is passed in. + +Global configuration to apply to every application defined in a file +should go in a special section named ``[DEFAULT]``. You can override +global configuration locally like:: + + [DEFAULT] + admin_email = webmaster@example.com + + [app:main] + use = ... + set admin_email = bob@example.com + +That is, by using ``set`` in front of the key. + +Composite Applications +~~~~~~~~~~~~~~~~~~~~~~ + +"Composite" applications are things that act like applications, but +are made up of other applications. One example would be a URL mapper, +where you mount applications at different URL paths. This might look +like:: + + [composite:main] + use = egg:Paste#urlmap + / = mainapp + /files = staticapp + + [app:mainapp] + use = egg:MyApp + + [app:staticapp] + use = egg:Paste#static + document_root = /path/to/docroot + +The composite application "main" is just like any other application +from the outside (you load it with ``loadapp`` for instance), but it +has access to other applications defined in the configuration file. + +Other Objects +~~~~~~~~~~~~~ + +In addition to sections with ``app:``, you can define filters and +servers in a configuration file, with ``server:`` and ``filter:`` +prefixes. You load these with ``loadserver`` and ``loadfilter``. The +configuration works just the same; you just get back different kinds +of objects. + +Filter Composition +~~~~~~~~~~~~~~~~~~ + +There are several ways to apply filters to applications. It mostly +depends on how many filters, and in what order you want to apply them. + +The first way is to use the ``filter-with`` setting, like:: + + [app:main] + use = egg:MyEgg + filter-with = printdebug + + [filter:printdebug] + use = egg:Paste#printdebug + # and you could have another filter-with here, and so on... + +Also, two special section types exist to apply filters to your +applications: ``[filter-app:...]`` and ``[pipeline:...]``. Both of +these sections define applications, and so can be used wherever an +application is needed. + +``filter-app`` defines a filter (just like you would in a +``[filter:...]`` section), and then a special key ``next`` which +points to the application to apply the filter to. + +``pipeline:`` is used when you need apply a number of filters. It +takes *one* configuration key ``pipeline`` (plus any global +configuration overrides you want). ``pipeline`` is a list of filters +ended by an application, like:: + + [pipeline:main] + pipeline = filter1 egg:FilterEgg#filter2 filter3 app + + [filter:filter1] + ... + +Getting Configuration +~~~~~~~~~~~~~~~~~~~~~ + +If you want to get the configuration without creating the application, +you can use the ``appconfig(uri)`` function, which is just like the +``loadapp()`` function except it returns the configuration that would +be used, as a dictionary. Both global and local configuration is +combined into a single dictionary, but you can look at just one or the +other with the attributes ``.local_conf`` and ``.global_conf``. + +``egg:`` URIs +------------- + +`Python Eggs `_ +are a distribution and installation format produced by `setuptools +`_ and +`distribute `_ that adds metadata to a +normal Python package (among other things). + +You don't need to understand a whole lot about Eggs to use them. If +you have a `distutils +`_ +``setup.py`` script, just change:: + + from distutils.core import setup + +to:: + + from setuptools import setup + +Now when you install the package it will be installed as an egg. + +The first important part about an Egg is that it has a +*specification*. This is formed from the name of your distribution +(the ``name`` keyword argument to ``setup()``), and you can specify a +specific version. So you can have an egg named ``MyApp``, or +``MyApp==0.1`` to specify a specific version. + +The second is *entry points*. These are references to Python objects +in your packages that are named and have a specific protocol. +"Protocol" here is just a way of saying that we will call them with +certain arguments, and expect a specific return value. We'll talk +more about the protocols later_. + +.. _later: `Defining Factories`_ + +The important part here is how we define entry points. You'll add an +argument to ``setup()`` like:: + + setup( + name='MyApp', + ... + entry_points={ + 'paste.app_factory': [ + 'main=myapp.mymodule:app_factory', + 'ob2=myapp.mymodule:ob_factory'], + }, + ) + +This defines two applications named ``main`` and ``ob2``. You can +then refer to these by ``egg:MyApp#main`` (or just ``egg:MyApp``, +since ``main`` is the default) and ``egg:MyApp#ob2``. + +The values are instructions for importing the objects. ``main`` is +located in the ``myapp.mymodule`` module, in an object named +``app_factory``. + +There's no way to add configuration to objects imported as Eggs. + +Defining Factories +------------------ + +This lets you point to factories (that obey the specific protocols we +mentioned). But that's not much use unless you can create factories +for your applications. + +There's a few protocols: ``paste.app_factory``, +``paste.composite_factory``, ``paste.filter_factory``, and lastly +``paste.server_factory``. Each of these expects a callable (like a +function, method, or class). + +``paste.app_factory`` +~~~~~~~~~~~~~~~~~~~~~~ + +The application is the most common. You define one like:: + + def app_factory(global_config, **local_conf): + return wsgi_app + +The ``global_config`` is a dictionary, and local configuration is +passed as keyword arguments. The function returns a WSGI application. + +``paste.composite_factory`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Composites are just slightly more complex:: + + def composite_factory(loader, global_config, **local_conf): + return wsgi_app + +The ``loader`` argument is an object that has a couple interesting +methods. ``get_app(name_or_uri, global_conf=None)`` return a WSGI +application with the given name. ``get_filter`` and ``get_server`` +work the same way. + +A more interesting example might be a composite factory that does +something. For instance, consider a "pipeline" application:: + + def pipeline_factory(loader, global_config, pipeline): + # space-separated list of filter and app names: + pipeline = pipeline.split() + filters = [loader.get_filter(n) for n in pipeline[:-1]] + app = loader.get_app(pipeline[-1]) + filters.reverse() # apply in reverse order! + for filter in filters: + app = filter(app) + return app + +Then we use it like:: + + [composite:main] + use = + pipeline = egg:Paste#printdebug session myapp + + [filter:session] + use = egg:Paste#session + store = memory + + [app:myapp] + use = egg:MyApp + +``paste.filter_factory`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filter factories are just like app factories (same signature), except +they return filters. Filters are callables that take a WSGI +application as the only argument, and return a "filtered" version of +that application. + +Here's an example of a filter that checks that the ``REMOTE_USER`` CGI +variable is set, creating a really simple authentication filter:: + + def auth_filter_factory(global_conf, req_usernames): + # space-separated list of usernames: + req_usernames = req_usernames.split() + def filter(app): + return AuthFilter(app, req_usernames) + return filter + + class AuthFilter(object): + def __init__(self, app, req_usernames): + self.app = app + self.req_usernames = req_usernames + + def __call__(self, environ, start_response): + if environ.get('REMOTE_USER') in self.req_usernames: + return self.app(environ, start_response) + start_response( + '403 Forbidden', [('Content-type', 'text/html')]) + return ['You are forbidden to view this resource'] + +``paste.filter_app_factory`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is very similar to ``paste.filter_factory``, except that it also +takes a ``wsgi_app`` argument, and returns a WSGI application. So if +you changed the above example to:: + + class AuthFilter(object): + def __init__(self, app, global_conf, req_usernames): + .... + +Then ``AuthFilter`` would serve as a filter_app_factory +(``req_usernames`` is a required local configuration key in this +case). + +``paste.server_factory`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This takes the same signature as applications and filters, but returns +a server. + +A server is a callable that takes a single argument, a WSGI +application. It then serves the application. + +An example might look like:: + + def server_factory(global_conf, host, port): + port = int(port) + def serve(app): + s = Server(app, host=host, port=port) + s.serve_forever() + return serve + +The implementation of ``Server`` is left to the user. + +``paste.server_runner`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Like ``paste.server_factory``, except ``wsgi_app`` is passed as the +first argument, and the server should run immediately. + +Outstanding Issues +------------------ + +* Should there be a "default" protocol for each type of object? Since + there's currently only one protocol, it seems like it makes sense + (in the future there could be multiple). Except that + ``paste.app_factory`` and ``paste.composite_factory`` overlap + considerably. + +* ConfigParser's INI parsing is kind of annoying. I'd like it both + more constrained and less constrained. Some parts are sloppy (like + the way it interprets ``[DEFAULT]``). + +* ``config:`` URLs should be potentially relative to other locations, + e.g., ``config:$docroot/...``. Maybe using variables from + ``global_conf``? + +* Should other variables have access to ``global_conf``? + +* Should objects be Python-syntax, instead of always strings? Lots of + code isn't usable with Python strings without a thin wrapper to + translate objects into their proper types. + +* Some short-form for a filter/app, where the filter refers to the + "next app". Maybe like:: + + [app-filter:app_name] + use = egg:... + next = next_app + + [app:next_app] + ... + diff --git a/docs/index.txt b/docs/index.txt deleted file mode 100644 index e6c4351..0000000 --- a/docs/index.txt +++ /dev/null @@ -1,671 +0,0 @@ -Paste Deployment -================ - -:author: Ian Bicking - -.. contents:: - -Documents: - -.. toctree:: - :maxdepth: 1 - - news - modules/loadwsgi - modules/config - modules/converters - -.. comment: - The names used in sections should be more concrete, and it should - be clearer that they are just arbitrary names. - -Introduction ------------- - -Paste Deployment is a system for finding and configuring WSGI -applications and servers. For WSGI application consumers it provides -a single, simple function (``loadapp``) for loading a WSGI application -from a configuration file or a Python Egg. For WSGI application -providers it only asks for a single, simple entry point to your -application, so that application users don't need to be exposed to the -implementation details of your application. - -The result is something a system administrator can install and manage -without knowing any Python, or the details of the WSGI application or -its container. - -Paste Deployment currently does not require other parts of `Paste -`_, and is distributed as a separate package. - -To see updates that have been made to Paste Deploy see the `news file -`_. - -Paste Deploy is released under the `MIT license -`_. - -Status ------- - -Paste Deploy has passed version 1.0. Paste Deploy is an actively -maintained project. As of 1.0, we'll make a strong effort to maintain -backward compatibility (this actually started happening long before -1.0, but now it is explicit). This will include deprecation warnings -when necessary. Major changes will take place under new functions or -with new entry points. - -Note that the most key aspect of Paste Deploy is the entry points it -defines (such as ``paste.app_factory``). Paste Deploy is not the only -consumer of these entry points, and many extensions can best take -place by utilizing the entry points instead of using Paste Deploy -directly. The entry points will not change; if changes are necessary, -new entry points will be defined. - -Installation ------------- - -First make sure you have either -`setuptools `_ or its -modern replacement -`distribute `_ installed. -For Python 3.x you need distribute as setuptools does not work on it. - -Then you can install Paste Deployment using `pip -`_ by running:: - - $ sudo pip install PasteDeploy - -If you want to track development, do:: - - $ hg clone http://bitbucket.org/ianb/pastedeploy - $ cd pastedeploy - $ sudo python setup.py develop - -This will install the package globally, but will load the files in the -checkout. You can also simply install ``PasteDeploy==dev``. - -For downloads and other information see the `Cheese Shop PasteDeploy -page `_. - -A complimentary package is `Paste Script `_. To install -that, use ``pip install PasteScript`` (or ``pip install -PasteScript==dev``). - -From the User Perspective -------------------------- - -In the following sections, the Python API for using Paste Deploy is -given. This isn't what users will be using (but it is useful for -Python developers and useful for setting up tests fixtures). - -The primary interaction with Paste Deploy is through its configuration -files. The primary thing you want to do with a configuration file is -serve it. To learn about serving configuration files, see `the -``paster serve`` command -`_. - -The Config File -~~~~~~~~~~~~~~~ - -A config file has different sections. The only sections Paste Deploy -cares about have prefixes, like ``app:main`` or ``filter:errors`` -- -the part after the ``:`` is the "name" of the section, and the part -before gives the "type". Other sections are ignored. - -The format is a simple `INI format -`_: ``name = value``. You can -extend the value by indenting subsequent lines. ``#`` is a comment. - -Typically you have one or two sections, named "main": an application -section (``[app:main]``) and a server section (``[server:main]``). -``[composite:...]`` signifies something that dispatches to multiple -applications (example below). - -Here's a typical configuration file that also shows off mounting -multiple applications using `paste.urlmap -`_:: - - [composite:main] - use = egg:Paste#urlmap - / = home - /blog = blog - /wiki = wiki - /cms = config:cms.ini - - [app:home] - use = egg:Paste#static - document_root = %(here)s/htdocs - - [filter-app:blog] - use = egg:Authentication#auth - next = blogapp - roles = admin - htpasswd = /home/me/users.htpasswd - - [app:blogapp] - use = egg:BlogApp - database = sqlite:/home/me/blog.db - - [app:wiki] - use = call:mywiki.main:application - database = sqlite:/home/me/wiki.db - -I'll explain each section in detail now:: - - [composite:main] - use = egg:Paste#urlmap - / = home - /blog = blog - /cms = config:cms.ini - -That this is a ``composite`` section means it dispatches the request -to other applications. ``use = egg:Paste#urlmap`` means to use the -composite application named ``urlmap`` from the ``Paste`` package. -``urlmap`` is a particularly common composite application -- it uses a -path prefix to map your request to another application. These are -the applications like "home", "blog", "wiki" and "config:cms.ini". The last -one just refers to another file ``cms.ini`` in the same directory. - -Next up:: - - [app:home] - use = egg:Paste#static - document_root = %(here)s/htdocs - -``egg:Paste#static`` is another simple application, in this case it -just serves up non-dynamic files. It takes one bit of configuration: -``document_root``. You can use variable substitution, which will pull -variables from the section ``[DEFAULT]`` (case sensitive!) with -markers like ``%(var_name)s``. The special variable ``%(here)s`` is -the directory containing the configuration file; you should use that -in lieu of relative filenames (which depend on the current directory, -which can change depending how the server is run). - -Then:: - - [filter-app:blog] - use = egg:Authentication#auth - next = blogapp - roles = admin - htpasswd = /home/me/users.htpasswd - - [app:blogapp] - use = egg:BlogApp - database = sqlite:/home/me/blog.db - -The ``[filter-app:blog]`` section means that you want an application -with a filter applied. The application being filtered is indicated -with ``next`` (which refers to the next section). The -``egg:Authentication#auth`` filter doesn't actually exist, but one -could imagine it logs people in and checks permissions. - -That last section is just a reference to an application that you -probably installed with ``pip install BlogApp``, and one bit of -configuration you passed to it (``database``). - -Lastly:: - - [app:wiki] - use = call:mywiki.main:application - database = sqlite:/home/me/wiki.db - -This section is similar to the previous one, with one important difference. -Instead of an entry point in an egg, it refers directly to the ``application`` -variable in the ``mywiki.main`` module. The reference consist of two parts, -separated by a colon. The left part is the full name of the module and the -right part is the path to the variable, as a Python expression relative to the -containing module. - -So, that's most of the features you'll use. - -Basic Usage ------------ - -The basic way you'll use Paste Deployment is to load `WSGI -`_ applications. Many -Python frameworks now support WSGI, so applications written for these -frameworks should be usable. - -The primary function is ``paste.deploy.loadapp``. This loads an -application given a URI. You can use it like:: - - from paste.deploy import loadapp - wsgi_app = loadapp('config:/path/to/config.ini') - -There's two URI formats currently supported: ``config:`` and ``egg:``. - -``config:`` URIs ----------------- - -URIs that being with ``config:`` refer to configuration files. These -filenames can be relative if you pass the ``relative_to`` keyword -argument to ``loadapp()``. - -.. note:: - - Filenames are never considered relative to the current working - directory, as that is a unpredictable location. Generally when - a URI has a context it will be seen as relative to that context; - for example, if you have a ``config:`` URI inside another - configuration file, the path is considered relative to the - directory that contains that configuration file. - -Config Format -~~~~~~~~~~~~~ - -Configuration files are in the INI format. This is a simple format -that looks like:: - - [section_name] - key = value - another key = a long value - that extends over multiple lines - -All values are strings (no quoting is necessary). The keys and -section names are case-sensitive, and may contain punctuation and -spaces (though both keys and values are stripped of leading and -trailing whitespace). Lines can be continued with leading whitespace. - -Lines beginning with ``#`` (preferred) or ``;`` are considered -comments. - -Applications -~~~~~~~~~~~~ - -You can define multiple applications in a single file; each -application goes in its own section. Even if you have just one -application, you must put it in a section. - -Each section name defining an application should be prefixed with -``app:``. The "main" section (when just defining one application) -would go in ``[app:main]`` or just ``[app]``. - -There's two ways to indicate the Python code for the application. The -first is to refer to another URI or name:: - - [app:myapp] - use = config:another_config_file.ini#app_name - - # or any URI: - [app:myotherapp] - use = egg:MyApp - - # or a callable from a module: - [app:mythirdapp] - use = call:my.project:myapplication - - # or even another section: - [app:mylastapp] - use = myotherapp - -It would seem at first that this was pointless; just a way to point to -another location. However, in addition to loading the application -from that location, you can also add or change the configuration. - -The other way to define an application is to point exactly to some -Python code:: - - [app:myapp] - paste.app_factory = myapp.modulename:app_factory - -You must give an explicit *protocol* (in this case -``paste.app_factory``), and the value is something to import. In -this case the module ``myapp.modulename`` is loaded, and the -``app_factory`` object retrieved from it. - -See `Defining Factories`_ for more about the protocols. - -Configuration -~~~~~~~~~~~~~ - -Configuration is done through keys besides ``use`` (or the protocol -names). Any other keys found in the section will be passed as keyword -arguments to the factory. This might look like:: - - [app:blog] - use = egg:MyBlog - database = mysql://localhost/blogdb - blogname = This Is My Blog! - -You can override these in other sections, like:: - - [app:otherblog] - use = blog - blogname = The other face of my blog - -This way some settings could be defined in a generic configuration -file (if you have ``use = config:other_config_file``) or you can -publish multiple (more specialized) applications just by adding a -section. - -Global Configuration -~~~~~~~~~~~~~~~~~~~~ - -Often many applications share the same configuration. While you can -do that a bit by using other config sections and overriding values, -often you want that done for a bunch of disparate configuration -values. And typically applications can't take "extra" configuration -parameters; with global configuration you do something equivalent to -"if this application wants to know the admin email, this is it". - -Applications are passed the global configuration separately, so they -must specifically pull values out of it; typically the global -configuration serves as the basis for defaults when no local -configuration is passed in. - -Global configuration to apply to every application defined in a file -should go in a special section named ``[DEFAULT]``. You can override -global configuration locally like:: - - [DEFAULT] - admin_email = webmaster@example.com - - [app:main] - use = ... - set admin_email = bob@example.com - -That is, by using ``set`` in front of the key. - -Composite Applications -~~~~~~~~~~~~~~~~~~~~~~ - -"Composite" applications are things that act like applications, but -are made up of other applications. One example would be a URL mapper, -where you mount applications at different URL paths. This might look -like:: - - [composite:main] - use = egg:Paste#urlmap - / = mainapp - /files = staticapp - - [app:mainapp] - use = egg:MyApp - - [app:staticapp] - use = egg:Paste#static - document_root = /path/to/docroot - -The composite application "main" is just like any other application -from the outside (you load it with ``loadapp`` for instance), but it -has access to other applications defined in the configuration file. - -Other Objects -~~~~~~~~~~~~~ - -In addition to sections with ``app:``, you can define filters and -servers in a configuration file, with ``server:`` and ``filter:`` -prefixes. You load these with ``loadserver`` and ``loadfilter``. The -configuration works just the same; you just get back different kinds -of objects. - -Filter Composition -~~~~~~~~~~~~~~~~~~ - -There are several ways to apply filters to applications. It mostly -depends on how many filters, and in what order you want to apply them. - -The first way is to use the ``filter-with`` setting, like:: - - [app:main] - use = egg:MyEgg - filter-with = printdebug - - [filter:printdebug] - use = egg:Paste#printdebug - # and you could have another filter-with here, and so on... - -Also, two special section types exist to apply filters to your -applications: ``[filter-app:...]`` and ``[pipeline:...]``. Both of -these sections define applications, and so can be used wherever an -application is needed. - -``filter-app`` defines a filter (just like you would in a -``[filter:...]`` section), and then a special key ``next`` which -points to the application to apply the filter to. - -``pipeline:`` is used when you need apply a number of filters. It -takes *one* configuration key ``pipeline`` (plus any global -configuration overrides you want). ``pipeline`` is a list of filters -ended by an application, like:: - - [pipeline:main] - pipeline = filter1 egg:FilterEgg#filter2 filter3 app - - [filter:filter1] - ... - -Getting Configuration -~~~~~~~~~~~~~~~~~~~~~ - -If you want to get the configuration without creating the application, -you can use the ``appconfig(uri)`` function, which is just like the -``loadapp()`` function except it returns the configuration that would -be used, as a dictionary. Both global and local configuration is -combined into a single dictionary, but you can look at just one or the -other with the attributes ``.local_conf`` and ``.global_conf``. - -``egg:`` URIs -------------- - -`Python Eggs `_ -are a distribution and installation format produced by `setuptools -`_ and -`distribute `_ that adds metadata to a -normal Python package (among other things). - -You don't need to understand a whole lot about Eggs to use them. If -you have a `distutils -`_ -``setup.py`` script, just change:: - - from distutils.core import setup - -to:: - - from setuptools import setup - -Now when you install the package it will be installed as an egg. - -The first important part about an Egg is that it has a -*specification*. This is formed from the name of your distribution -(the ``name`` keyword argument to ``setup()``), and you can specify a -specific version. So you can have an egg named ``MyApp``, or -``MyApp==0.1`` to specify a specific version. - -The second is *entry points*. These are references to Python objects -in your packages that are named and have a specific protocol. -"Protocol" here is just a way of saying that we will call them with -certain arguments, and expect a specific return value. We'll talk -more about the protocols later_. - -.. _later: `Defining Factories`_ - -The important part here is how we define entry points. You'll add an -argument to ``setup()`` like:: - - setup( - name='MyApp', - ... - entry_points={ - 'paste.app_factory': [ - 'main=myapp.mymodule:app_factory', - 'ob2=myapp.mymodule:ob_factory'], - }, - ) - -This defines two applications named ``main`` and ``ob2``. You can -then refer to these by ``egg:MyApp#main`` (or just ``egg:MyApp``, -since ``main`` is the default) and ``egg:MyApp#ob2``. - -The values are instructions for importing the objects. ``main`` is -located in the ``myapp.mymodule`` module, in an object named -``app_factory``. - -There's no way to add configuration to objects imported as Eggs. - -Defining Factories ------------------- - -This lets you point to factories (that obey the specific protocols we -mentioned). But that's not much use unless you can create factories -for your applications. - -There's a few protocols: ``paste.app_factory``, -``paste.composite_factory``, ``paste.filter_factory``, and lastly -``paste.server_factory``. Each of these expects a callable (like a -function, method, or class). - -``paste.app_factory`` -~~~~~~~~~~~~~~~~~~~~~~ - -The application is the most common. You define one like:: - - def app_factory(global_config, **local_conf): - return wsgi_app - -The ``global_config`` is a dictionary, and local configuration is -passed as keyword arguments. The function returns a WSGI application. - -``paste.composite_factory`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Composites are just slightly more complex:: - - def composite_factory(loader, global_config, **local_conf): - return wsgi_app - -The ``loader`` argument is an object that has a couple interesting -methods. ``get_app(name_or_uri, global_conf=None)`` return a WSGI -application with the given name. ``get_filter`` and ``get_server`` -work the same way. - -A more interesting example might be a composite factory that does -something. For instance, consider a "pipeline" application:: - - def pipeline_factory(loader, global_config, pipeline): - # space-separated list of filter and app names: - pipeline = pipeline.split() - filters = [loader.get_filter(n) for n in pipeline[:-1]] - app = loader.get_app(pipeline[-1]) - filters.reverse() # apply in reverse order! - for filter in filters: - app = filter(app) - return app - -Then we use it like:: - - [composite:main] - use = - pipeline = egg:Paste#printdebug session myapp - - [filter:session] - use = egg:Paste#session - store = memory - - [app:myapp] - use = egg:MyApp - -``paste.filter_factory`` -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Filter factories are just like app factories (same signature), except -they return filters. Filters are callables that take a WSGI -application as the only argument, and return a "filtered" version of -that application. - -Here's an example of a filter that checks that the ``REMOTE_USER`` CGI -variable is set, creating a really simple authentication filter:: - - def auth_filter_factory(global_conf, req_usernames): - # space-separated list of usernames: - req_usernames = req_usernames.split() - def filter(app): - return AuthFilter(app, req_usernames) - return filter - - class AuthFilter(object): - def __init__(self, app, req_usernames): - self.app = app - self.req_usernames = req_usernames - - def __call__(self, environ, start_response): - if environ.get('REMOTE_USER') in self.req_usernames: - return self.app(environ, start_response) - start_response( - '403 Forbidden', [('Content-type', 'text/html')]) - return ['You are forbidden to view this resource'] - -``paste.filter_app_factory`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is very similar to ``paste.filter_factory``, except that it also -takes a ``wsgi_app`` argument, and returns a WSGI application. So if -you changed the above example to:: - - class AuthFilter(object): - def __init__(self, app, global_conf, req_usernames): - .... - -Then ``AuthFilter`` would serve as a filter_app_factory -(``req_usernames`` is a required local configuration key in this -case). - -``paste.server_factory`` -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This takes the same signature as applications and filters, but returns -a server. - -A server is a callable that takes a single argument, a WSGI -application. It then serves the application. - -An example might look like:: - - def server_factory(global_conf, host, port): - port = int(port) - def serve(app): - s = Server(app, host=host, port=port) - s.serve_forever() - return serve - -The implementation of ``Server`` is left to the user. - -``paste.server_runner`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -Like ``paste.server_factory``, except ``wsgi_app`` is passed as the -first argument, and the server should run immediately. - -Outstanding Issues ------------------- - -* Should there be a "default" protocol for each type of object? Since - there's currently only one protocol, it seems like it makes sense - (in the future there could be multiple). Except that - ``paste.app_factory`` and ``paste.composite_factory`` overlap - considerably. - -* ConfigParser's INI parsing is kind of annoying. I'd like it both - more constrained and less constrained. Some parts are sloppy (like - the way it interprets ``[DEFAULT]``). - -* ``config:`` URLs should be potentially relative to other locations, - e.g., ``config:$docroot/...``. Maybe using variables from - ``global_conf``? - -* Should other variables have access to ``global_conf``? - -* Should objects be Python-syntax, instead of always strings? Lots of - code isn't usable with Python strings without a thin wrapper to - translate objects into their proper types. - -* Some short-form for a filter/app, where the filter refers to the - "next app". Maybe like:: - - [app-filter:app_name] - use = egg:... - next = next_app - - [app:next_app] - ... - diff --git a/docs/news.rst b/docs/news.rst new file mode 100644 index 0000000..bc1e987 --- /dev/null +++ b/docs/news.rst @@ -0,0 +1,179 @@ +Paste Deployment News +===================== + +1.5.2 +----- + +* Fixed Python 3 issue in paste.deploy.util.fix_type_error() + +1.5.1 +----- + +* Fixed use of the wrong variable when determining the context protocol + +* Fixed invalid import of paste.deploy.Config to paste.deploy.config.Config + +* Fixed multi proxy IPs bug in X-Forwarded-For header in PrefixMiddleware + +* Fixed TypeError when trying to raise LookupError on Python 3 + +* Fixed exception reraise on Python 3 + +Thanks to Alexandre Conrad, Atsushi Odagiri, Pior Bastida and Tres Seaver for their contributions. + +1.5.0 +----- + +* Project is now maintained by Alex Grönholm + +* Was printing extraneous data when calling setup.py + +* Fixed missing paster template files (fixes "paster create -t paste.deploy") + +* Excluded tests from release distributions + +* Added support for the "call:" protocol for loading apps directly as + functions (contributed by Jason Stitt) + +* Added Python 3.x support + +* Dropped Python 2.4 support + +* Removed the ``paste.deploy.epdesc`` and ``paste.deploy.interfaces`` modules + -- contact the maintainer if you actually needed them + +1.3.4 +----- + +* Fix loadconfig path handling on Jython on Windows. + +1.3.3 +----- + +* In :class:`paste.deploy.config.PrefixMiddleware` the headers + ``X-Forwarded-Scheme`` and ``X-Forwarded-Proto`` are now translated + to the key ``environ['wsgi.url_scheme']``. Also ``X-Forwarded-For`` + is translated to ``environ['REMOTE_ADDR']`` + +* Also in PrefixMiddleware, if X-Forwarded-Host has multiple + (comma-separated) values, use only the first value. + +1.3.2 +----- + +* Added ``paste.deploy.converters.asint()``. +* fixed use sections overwriting the config's __file__ value with the + use'd filename. +* ``paste.deploy.loadwsgi`` now supports variable expansion in the + DEFAULT section of config files (unlike plain ConfigParser). + +1.3.1 +----- + +* Fix ``appconfig`` config loading when using a config file with + ``filter-with`` in it (previously you'd get TypeError: iteration + over non-sequence) + +1.3 +--- + +* Added ``scheme`` option to ``PrefixMiddleware``, so you can force a + scheme (E.g., when proxying an HTTPS connection over HTTP). + +* Pop proper values into ``environ['paste.config']`` in + ``ConfigMiddleware``. + +1.1 +--- + +* Any ``global_conf`` extra keys you pass to ``loadapp`` (or the other + loaders) will show up as though they were in ``[DEFAULT]``, so they + can be used in variable interpolation. Note: this won't overwrite + any existing values in ``[DEFAULT]``. + +* Added ``force_port`` option to + ``paste.deploy.config.PrefixMiddleware``. Also the ``prefix`` + argument is stripped of any trailing ``/``, which can't be valid in + that position. + +1.0 +--- + +* Added some documentation for the different kinds of entry points + Paste Deploy uses. + +* Added a feature to ``PrefixMiddleware`` that translates the + ``X-Forwarded-Server`` header to ``Host``. + +0.9.6 +----- + +* Added ``PrefixMiddleware`` which compensates for cases where the + wsgi app is behind a proxy of some sort that isn't moving the prefix + into the SCRIPT_NAME in advance. + +* Changed _loadconfig() so that it works with Windows absolute paths. + +* Make the error messages prettier when you call a function and fail + to give an argument, like a required function argument. + +0.5 +--- + +* Made the ``paste_deploy`` template (used with ``paster create + --template=paste_deploy``) more useful, with an example application + and entry point. + +0.4 +--- + +* Allow filters to have ``filter-with`` values, just like + applications. + +* Renamed ``composit`` to ``composite`` (old names still work, but + aren't documented). + +* Added ``appconfig()`` to load along with ``loadapp()``, but return + the configuration without invoking the application. + +0.3 +--- + +* Allow variable setting like:: + + get local_var = global_var_name + + To bring in global variables to the local scope. + +* Allow interpolation in files, like ``%(here)s``. Anything in the + ``[DEFAULTS]`` section will be available to substitute into a value, + as will variables in the same section. Also, the special value + ``here`` will be the directory the configuration file is located in. + +0.2 +--- + +Released 26 August 2004 + +* Added a ``filter-with`` setting to applications. + +* Removed the ``1`` from all the protocol names (e.g., + ``paste.app_factory1`` is not ``paste.app_factory``). + +* Added ``filter-app:`` and ``pipeline:`` sections. `Docs + `__. + +* Added ``paste.filter_app_factory1`` (`doc + `__) and + ``paste.server_runner1`` (`doc + `__) protocols. + +* Added ``paste.deploy.converters`` module for handling the + string values that are common with this system. + +0.1 +--- + +Released 22 August 2004 + +Initial version released. It's all new. diff --git a/docs/news.txt b/docs/news.txt deleted file mode 100644 index bc1e987..0000000 --- a/docs/news.txt +++ /dev/null @@ -1,179 +0,0 @@ -Paste Deployment News -===================== - -1.5.2 ------ - -* Fixed Python 3 issue in paste.deploy.util.fix_type_error() - -1.5.1 ------ - -* Fixed use of the wrong variable when determining the context protocol - -* Fixed invalid import of paste.deploy.Config to paste.deploy.config.Config - -* Fixed multi proxy IPs bug in X-Forwarded-For header in PrefixMiddleware - -* Fixed TypeError when trying to raise LookupError on Python 3 - -* Fixed exception reraise on Python 3 - -Thanks to Alexandre Conrad, Atsushi Odagiri, Pior Bastida and Tres Seaver for their contributions. - -1.5.0 ------ - -* Project is now maintained by Alex Grönholm - -* Was printing extraneous data when calling setup.py - -* Fixed missing paster template files (fixes "paster create -t paste.deploy") - -* Excluded tests from release distributions - -* Added support for the "call:" protocol for loading apps directly as - functions (contributed by Jason Stitt) - -* Added Python 3.x support - -* Dropped Python 2.4 support - -* Removed the ``paste.deploy.epdesc`` and ``paste.deploy.interfaces`` modules - -- contact the maintainer if you actually needed them - -1.3.4 ------ - -* Fix loadconfig path handling on Jython on Windows. - -1.3.3 ------ - -* In :class:`paste.deploy.config.PrefixMiddleware` the headers - ``X-Forwarded-Scheme`` and ``X-Forwarded-Proto`` are now translated - to the key ``environ['wsgi.url_scheme']``. Also ``X-Forwarded-For`` - is translated to ``environ['REMOTE_ADDR']`` - -* Also in PrefixMiddleware, if X-Forwarded-Host has multiple - (comma-separated) values, use only the first value. - -1.3.2 ------ - -* Added ``paste.deploy.converters.asint()``. -* fixed use sections overwriting the config's __file__ value with the - use'd filename. -* ``paste.deploy.loadwsgi`` now supports variable expansion in the - DEFAULT section of config files (unlike plain ConfigParser). - -1.3.1 ------ - -* Fix ``appconfig`` config loading when using a config file with - ``filter-with`` in it (previously you'd get TypeError: iteration - over non-sequence) - -1.3 ---- - -* Added ``scheme`` option to ``PrefixMiddleware``, so you can force a - scheme (E.g., when proxying an HTTPS connection over HTTP). - -* Pop proper values into ``environ['paste.config']`` in - ``ConfigMiddleware``. - -1.1 ---- - -* Any ``global_conf`` extra keys you pass to ``loadapp`` (or the other - loaders) will show up as though they were in ``[DEFAULT]``, so they - can be used in variable interpolation. Note: this won't overwrite - any existing values in ``[DEFAULT]``. - -* Added ``force_port`` option to - ``paste.deploy.config.PrefixMiddleware``. Also the ``prefix`` - argument is stripped of any trailing ``/``, which can't be valid in - that position. - -1.0 ---- - -* Added some documentation for the different kinds of entry points - Paste Deploy uses. - -* Added a feature to ``PrefixMiddleware`` that translates the - ``X-Forwarded-Server`` header to ``Host``. - -0.9.6 ------ - -* Added ``PrefixMiddleware`` which compensates for cases where the - wsgi app is behind a proxy of some sort that isn't moving the prefix - into the SCRIPT_NAME in advance. - -* Changed _loadconfig() so that it works with Windows absolute paths. - -* Make the error messages prettier when you call a function and fail - to give an argument, like a required function argument. - -0.5 ---- - -* Made the ``paste_deploy`` template (used with ``paster create - --template=paste_deploy``) more useful, with an example application - and entry point. - -0.4 ---- - -* Allow filters to have ``filter-with`` values, just like - applications. - -* Renamed ``composit`` to ``composite`` (old names still work, but - aren't documented). - -* Added ``appconfig()`` to load along with ``loadapp()``, but return - the configuration without invoking the application. - -0.3 ---- - -* Allow variable setting like:: - - get local_var = global_var_name - - To bring in global variables to the local scope. - -* Allow interpolation in files, like ``%(here)s``. Anything in the - ``[DEFAULTS]`` section will be available to substitute into a value, - as will variables in the same section. Also, the special value - ``here`` will be the directory the configuration file is located in. - -0.2 ---- - -Released 26 August 2004 - -* Added a ``filter-with`` setting to applications. - -* Removed the ``1`` from all the protocol names (e.g., - ``paste.app_factory1`` is not ``paste.app_factory``). - -* Added ``filter-app:`` and ``pipeline:`` sections. `Docs - `__. - -* Added ``paste.filter_app_factory1`` (`doc - `__) and - ``paste.server_runner1`` (`doc - `__) protocols. - -* Added ``paste.deploy.converters`` module for handling the - string values that are common with this system. - -0.1 ---- - -Released 22 August 2004 - -Initial version released. It's all new. -- cgit v1.2.1 From c308646ef40e456c6821e45b1d5620f72ccda13e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:02:53 -0800 Subject: Remove obsolete script --- regen-docs | 9 --------- 1 file changed, 9 deletions(-) delete mode 100755 regen-docs diff --git a/regen-docs b/regen-docs deleted file mode 100755 index f8dad75..0000000 --- a/regen-docs +++ /dev/null @@ -1,9 +0,0 @@ -#!/bin/sh - -mkdir -p docs/_static docs/_build -sphinx-build -E -b html docs/ docs/_build || exit 1 -if [ "$1" = "publish" ] ; then - cd docs/ - echo "Uploading files..." - scp -r _build/* ianb@webwareforpython.org:/home/paste/htdocs/deploy/ -fi -- cgit v1.2.1 From d601938327025ab4dc83a722301eecac4a5ea32d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:06:49 -0800 Subject: Modernize conf.py so we don't have to keep updating it for each release and year --- docs/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c2c3191..d89e68b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,7 +11,8 @@ # All configuration values have a default value; values that are commented out # serve to show the default value. -import sys +import datetime +import pkg_resources import pylons_sphinx_themes # If your extensions are in another directory, add it here. @@ -34,16 +35,18 @@ source_suffix = '.rst' master_doc = 'index' # General substitutions. +thisyear = datetime.datetime.now().year project = 'Paste Deploy' -copyright = '2011, Ian Bicking and contributors' +copyright = '2011-%s, Ian Bicking and contributors' % thisyear # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. # # The short X.Y version. -version = '1.5' +version = pkg_resources.get_distribution('pastedeploy').version + # The full version, including alpha/beta/rc tags. -release = '1.5.2' +release = version # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -- cgit v1.2.1 From 51598458f205877cb1c574e71ffa5a84a1165b6e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:19:27 -0800 Subject: Comment out templates path as it is not used --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index d89e68b..7cffcb2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,7 +26,7 @@ import pylons_sphinx_themes extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +# templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' -- cgit v1.2.1 From 8a894549dcc42ba76f4dd1b0d21f00ff37a10bac Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:19:58 -0800 Subject: Use correct syntax highlighting --- docs/index.rst | 121 ++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 86 insertions(+), 35 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index e6c4351..0281128 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,16 +69,19 @@ modern replacement `distribute `_ installed. For Python 3.x you need distribute as setuptools does not work on it. -Then you can install Paste Deployment using `pip -`_ by running:: +Then you can install Paste Deployment using `pip `_ by running: - $ sudo pip install PasteDeploy +.. code-block:: bash -If you want to track development, do:: + sudo pip install PasteDeploy - $ hg clone http://bitbucket.org/ianb/pastedeploy - $ cd pastedeploy - $ sudo python setup.py develop +If you want to track development, do: + +.. code-block:: bash + + hg clone http://bitbucket.org/ianb/pastedeploy + cd pastedeploy + sudo python setup.py develop This will install the package globally, but will load the files in the checkout. You can also simply install ``PasteDeploy==dev``. @@ -122,7 +125,9 @@ applications (example below). Here's a typical configuration file that also shows off mounting multiple applications using `paste.urlmap -`_:: +`_: + +.. code-block:: ini [composite:main] use = egg:Paste#urlmap @@ -149,7 +154,9 @@ multiple applications using `paste.urlmap use = call:mywiki.main:application database = sqlite:/home/me/wiki.db -I'll explain each section in detail now:: +I'll explain each section in detail now: + +.. code-block:: ini [composite:main] use = egg:Paste#urlmap @@ -165,7 +172,9 @@ path prefix to map your request to another application. These are the applications like "home", "blog", "wiki" and "config:cms.ini". The last one just refers to another file ``cms.ini`` in the same directory. -Next up:: +Next up: + +.. code-block:: ini [app:home] use = egg:Paste#static @@ -180,7 +189,9 @@ the directory containing the configuration file; you should use that in lieu of relative filenames (which depend on the current directory, which can change depending how the server is run). -Then:: +Then: + +.. code-block:: ini [filter-app:blog] use = egg:Authentication#auth @@ -202,7 +213,9 @@ That last section is just a reference to an application that you probably installed with ``pip install BlogApp``, and one bit of configuration you passed to it (``database``). -Lastly:: +Lastly: + +.. code-block:: ini [app:wiki] use = call:mywiki.main:application @@ -280,7 +293,9 @@ Each section name defining an application should be prefixed with would go in ``[app:main]`` or just ``[app]``. There's two ways to indicate the Python code for the application. The -first is to refer to another URI or name:: +first is to refer to another URI or name: + +.. code-block:: ini [app:myapp] use = config:another_config_file.ini#app_name @@ -302,7 +317,9 @@ another location. However, in addition to loading the application from that location, you can also add or change the configuration. The other way to define an application is to point exactly to some -Python code:: +Python code: + +.. code-block:: ini [app:myapp] paste.app_factory = myapp.modulename:app_factory @@ -319,14 +336,18 @@ Configuration Configuration is done through keys besides ``use`` (or the protocol names). Any other keys found in the section will be passed as keyword -arguments to the factory. This might look like:: +arguments to the factory. This might look like: + +.. code-block:: ini [app:blog] use = egg:MyBlog database = mysql://localhost/blogdb blogname = This Is My Blog! -You can override these in other sections, like:: +You can override these in other sections, like: + +.. code-block:: ini [app:otherblog] use = blog @@ -354,7 +375,9 @@ configuration is passed in. Global configuration to apply to every application defined in a file should go in a special section named ``[DEFAULT]``. You can override -global configuration locally like:: +global configuration locally like: + +.. code-block:: ini [DEFAULT] admin_email = webmaster@example.com @@ -371,7 +394,9 @@ Composite Applications "Composite" applications are things that act like applications, but are made up of other applications. One example would be a URL mapper, where you mount applications at different URL paths. This might look -like:: +like: + +.. code-block:: ini [composite:main] use = egg:Paste#urlmap @@ -404,7 +429,9 @@ Filter Composition There are several ways to apply filters to applications. It mostly depends on how many filters, and in what order you want to apply them. -The first way is to use the ``filter-with`` setting, like:: +The first way is to use the ``filter-with`` setting, like: + +.. code-block:: ini [app:main] use = egg:MyEgg @@ -426,13 +453,15 @@ points to the application to apply the filter to. ``pipeline:`` is used when you need apply a number of filters. It takes *one* configuration key ``pipeline`` (plus any global configuration overrides you want). ``pipeline`` is a list of filters -ended by an application, like:: +ended by an application, like: + +.. code-block:: ini [pipeline:main] pipeline = filter1 egg:FilterEgg#filter2 filter3 app [filter:filter1] - ... + # ... Getting Configuration ~~~~~~~~~~~~~~~~~~~~~ @@ -456,11 +485,15 @@ normal Python package (among other things). You don't need to understand a whole lot about Eggs to use them. If you have a `distutils `_ -``setup.py`` script, just change:: +``setup.py`` script, just change: + +.. code-block:: python from distutils.core import setup -to:: +to: + +.. code-block:: python from setuptools import setup @@ -481,11 +514,13 @@ more about the protocols later_. .. _later: `Defining Factories`_ The important part here is how we define entry points. You'll add an -argument to ``setup()`` like:: +argument to ``setup()`` like: + +.. code-block:: python setup( name='MyApp', - ... + # ... entry_points={ 'paste.app_factory': [ 'main=myapp.mymodule:app_factory', @@ -518,7 +553,9 @@ function, method, or class). ``paste.app_factory`` ~~~~~~~~~~~~~~~~~~~~~~ -The application is the most common. You define one like:: +The application is the most common. You define one like: + +.. code-block:: python def app_factory(global_config, **local_conf): return wsgi_app @@ -529,7 +566,9 @@ passed as keyword arguments. The function returns a WSGI application. ``paste.composite_factory`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Composites are just slightly more complex:: +Composites are just slightly more complex: + +.. code-block:: python def composite_factory(loader, global_config, **local_conf): return wsgi_app @@ -540,7 +579,9 @@ application with the given name. ``get_filter`` and ``get_server`` work the same way. A more interesting example might be a composite factory that does -something. For instance, consider a "pipeline" application:: +something. For instance, consider a "pipeline" application: + +.. code-block:: python def pipeline_factory(loader, global_config, pipeline): # space-separated list of filter and app names: @@ -552,7 +593,9 @@ something. For instance, consider a "pipeline" application:: app = filter(app) return app -Then we use it like:: +Then we use it like: + +.. code-block:: ini [composite:main] use = @@ -574,7 +617,9 @@ application as the only argument, and return a "filtered" version of that application. Here's an example of a filter that checks that the ``REMOTE_USER`` CGI -variable is set, creating a really simple authentication filter:: +variable is set, creating a really simple authentication filter: + +.. code-block:: python def auth_filter_factory(global_conf, req_usernames): # space-separated list of usernames: @@ -600,11 +645,13 @@ variable is set, creating a really simple authentication filter:: This is very similar to ``paste.filter_factory``, except that it also takes a ``wsgi_app`` argument, and returns a WSGI application. So if -you changed the above example to:: +you changed the above example to: + +.. code-block:: python class AuthFilter(object): def __init__(self, app, global_conf, req_usernames): - .... + # ... Then ``AuthFilter`` would serve as a filter_app_factory (``req_usernames`` is a required local configuration key in this @@ -619,7 +666,9 @@ a server. A server is a callable that takes a single argument, a WSGI application. It then serves the application. -An example might look like:: +An example might look like: + +.. code-block:: python def server_factory(global_conf, host, port): port = int(port) @@ -660,12 +709,14 @@ Outstanding Issues translate objects into their proper types. * Some short-form for a filter/app, where the filter refers to the - "next app". Maybe like:: + "next app". Maybe like: + +.. code-block:: ini [app-filter:app_name] use = egg:... next = next_app [app:next_app] - ... + # ... -- cgit v1.2.1 From 81f4a4893ca1b6754de50b47bb53c4e3cbb714c8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:20:17 -0800 Subject: Fix links to news and pip --- docs/index.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 0281128..66fa9e9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,8 +37,7 @@ its container. Paste Deployment currently does not require other parts of `Paste `_, and is distributed as a separate package. -To see updates that have been made to Paste Deploy see the `news file -`_. +To see updates that have been made to Paste Deploy see the :doc:`news file `_. Paste Deploy is released under the `MIT license `_. @@ -89,9 +88,8 @@ checkout. You can also simply install ``PasteDeploy==dev``. For downloads and other information see the `Cheese Shop PasteDeploy page `_. -A complimentary package is `Paste Script `_. To install -that, use ``pip install PasteScript`` (or ``pip install -PasteScript==dev``). +A complimentary package is `Paste Script `_. +To install that, use ``pip install PasteScript`` (or ``pip install PasteScript==dev``). From the User Perspective ------------------------- -- cgit v1.2.1 From 532a26dcfcd791deb98837a4429e26abe3b3e1b7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:39:37 -0800 Subject: update installation instructions --- docs/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 66fa9e9..9b4d1b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,17 +72,17 @@ Then you can install Paste Deployment using `pip .. code-block:: bash - sudo pip install PasteDeploy + pip install PasteDeploy If you want to track development, do: .. code-block:: bash - hg clone http://bitbucket.org/ianb/pastedeploy + git clone https://github.com/Pylons/pastedeploy cd pastedeploy - sudo python setup.py develop + pip install -e . -This will install the package globally, but will load the files in the +This will install the package locally, and will load the files in the checkout. You can also simply install ``PasteDeploy==dev``. For downloads and other information see the `Cheese Shop PasteDeploy -- cgit v1.2.1 From 5308aca631e72f4641db35061f6a58a588bd398a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:40:04 -0800 Subject: rename directory of reST files to use .rst extension --- docs/modules/config.rst | 13 +++++++++++++ docs/modules/config.txt | 13 ------------- docs/modules/converters.rst | 11 +++++++++++ docs/modules/converters.txt | 11 ----------- docs/modules/loadwsgi.rst | 13 +++++++++++++ docs/modules/loadwsgi.txt | 13 ------------- 6 files changed, 37 insertions(+), 37 deletions(-) create mode 100644 docs/modules/config.rst delete mode 100644 docs/modules/config.txt create mode 100644 docs/modules/converters.rst delete mode 100644 docs/modules/converters.txt create mode 100644 docs/modules/loadwsgi.rst delete mode 100644 docs/modules/loadwsgi.txt diff --git a/docs/modules/config.rst b/docs/modules/config.rst new file mode 100644 index 0000000..9d8f894 --- /dev/null +++ b/docs/modules/config.rst @@ -0,0 +1,13 @@ +:mod:`paste.deploy.config` -- Configuration and Environment middleware +====================================================================== + +.. automodule:: paste.deploy.config + +Module Contents +--------------- + +.. autoclass:: DispatchingConfig +.. autoclass:: ConfigMiddleware +.. autoclass:: PrefixMiddleware + +.. comment: FIXME: do something about CONFIG (manual docs?) diff --git a/docs/modules/config.txt b/docs/modules/config.txt deleted file mode 100644 index 9d8f894..0000000 --- a/docs/modules/config.txt +++ /dev/null @@ -1,13 +0,0 @@ -:mod:`paste.deploy.config` -- Configuration and Environment middleware -====================================================================== - -.. automodule:: paste.deploy.config - -Module Contents ---------------- - -.. autoclass:: DispatchingConfig -.. autoclass:: ConfigMiddleware -.. autoclass:: PrefixMiddleware - -.. comment: FIXME: do something about CONFIG (manual docs?) diff --git a/docs/modules/converters.rst b/docs/modules/converters.rst new file mode 100644 index 0000000..4948104 --- /dev/null +++ b/docs/modules/converters.rst @@ -0,0 +1,11 @@ +:mod:`paste.deploy.converters` -- Conversion helpers for String Configuration +============================================================================= + +.. automodule:: paste.deploy.converters + +Module Contents +--------------- + +.. autofunction:: asbool +.. autofunction:: asint +.. autofunction:: aslist diff --git a/docs/modules/converters.txt b/docs/modules/converters.txt deleted file mode 100644 index 4948104..0000000 --- a/docs/modules/converters.txt +++ /dev/null @@ -1,11 +0,0 @@ -:mod:`paste.deploy.converters` -- Conversion helpers for String Configuration -============================================================================= - -.. automodule:: paste.deploy.converters - -Module Contents ---------------- - -.. autofunction:: asbool -.. autofunction:: asint -.. autofunction:: aslist diff --git a/docs/modules/loadwsgi.rst b/docs/modules/loadwsgi.rst new file mode 100644 index 0000000..feebf28 --- /dev/null +++ b/docs/modules/loadwsgi.rst @@ -0,0 +1,13 @@ +:mod:`paste.deploy.loadwsgi` -- Load WSGI applications from config files +======================================================================== + +.. automodule:: paste.deploy.loadwsgi + +Module Contents +--------------- + +.. autofunction:: loadapp +.. autofunction:: loadserver +.. autofunction:: loadfilter +.. autofunction:: appconfig + diff --git a/docs/modules/loadwsgi.txt b/docs/modules/loadwsgi.txt deleted file mode 100644 index feebf28..0000000 --- a/docs/modules/loadwsgi.txt +++ /dev/null @@ -1,13 +0,0 @@ -:mod:`paste.deploy.loadwsgi` -- Load WSGI applications from config files -======================================================================== - -.. automodule:: paste.deploy.loadwsgi - -Module Contents ---------------- - -.. autofunction:: loadapp -.. autofunction:: loadserver -.. autofunction:: loadfilter -.. autofunction:: appconfig - -- cgit v1.2.1 From 00b791de28f6862a8b533d5787ca622b3123a9f6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:58:47 -0800 Subject: Add intersphinx and configure Python docs --- docs/conf.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7cffcb2..8ac46d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,15 @@ import pylons_sphinx_themes # 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'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', +] + +# Looks for objects in external projects +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] -- cgit v1.2.1 From d8ec697639345db5274f90a4a425bb197c6c6b3b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:59:06 -0800 Subject: Remove dead links --- docs/news.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/news.rst b/docs/news.rst index bc1e987..0f4e309 100644 --- a/docs/news.rst +++ b/docs/news.rst @@ -160,13 +160,9 @@ Released 26 August 2004 * Removed the ``1`` from all the protocol names (e.g., ``paste.app_factory1`` is not ``paste.app_factory``). -* Added ``filter-app:`` and ``pipeline:`` sections. `Docs - `__. +* Added ``filter-app:`` and ``pipeline:`` sections. -* Added ``paste.filter_app_factory1`` (`doc - `__) and - ``paste.server_runner1`` (`doc - `__) protocols. +* Added ``paste.filter_app_factory1`` and ``paste.server_runner1`` protocols. * Added ``paste.deploy.converters`` module for handling the string values that are common with this system. -- cgit v1.2.1 From bcaefd4cca48cb0ccf16eb288e6044a6d75acb01 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 04:59:26 -0800 Subject: Use current links --- docs/index.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 9b4d1b9..24434b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,12 +35,12 @@ without knowing any Python, or the details of the WSGI application or its container. Paste Deployment currently does not require other parts of `Paste -`_, and is distributed as a separate package. +`_, and is distributed as a separate package. To see updates that have been made to Paste Deploy see the :doc:`news file `_. Paste Deploy is released under the `MIT license -`_. +`_. Status ------ @@ -85,8 +85,7 @@ If you want to track development, do: This will install the package locally, and will load the files in the checkout. You can also simply install ``PasteDeploy==dev``. -For downloads and other information see the `Cheese Shop PasteDeploy -page `_. +For downloads and other information see the `PyPI PasteDeploy page `_. A complimentary package is `Paste Script `_. To install that, use ``pip install PasteScript`` (or ``pip install PasteScript==dev``). @@ -102,7 +101,7 @@ The primary interaction with Paste Deploy is through its configuration files. The primary thing you want to do with a configuration file is serve it. To learn about serving configuration files, see `the ``paster serve`` command -`_. +`_. The Config File ~~~~~~~~~~~~~~~ @@ -113,7 +112,7 @@ the part after the ``:`` is the "name" of the section, and the part before gives the "type". Other sections are ignored. The format is a simple `INI format -`_: ``name = value``. You can +`_: ``name = value``. You can extend the value by indenting subsequent lines. ``#`` is a comment. Typically you have one or two sections, named "main": an application @@ -123,7 +122,7 @@ applications (example below). Here's a typical configuration file that also shows off mounting multiple applications using `paste.urlmap -`_: +`_: .. code-block:: ini @@ -232,7 +231,7 @@ Basic Usage ----------- The basic way you'll use Paste Deployment is to load `WSGI -`_ applications. Many +`_ applications. Many Python frameworks now support WSGI, so applications written for these frameworks should be usable. @@ -481,9 +480,7 @@ are a distribution and installation format produced by `setuptools normal Python package (among other things). You don't need to understand a whole lot about Eggs to use them. If -you have a `distutils -`_ -``setup.py`` script, just change: +you have a :mod:`` ``setup.py`` script, just change: .. code-block:: python -- cgit v1.2.1 From 8155528ceb20ba12bb0b18a0d9db4fe042c2a9e3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 10:33:14 -0800 Subject: Update link to Paste, saving a redirect https://pythonpaste.readthedocs.io/en/latest/ --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 24434b7..2ef8f07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,7 +35,7 @@ without knowing any Python, or the details of the WSGI application or its container. Paste Deployment currently does not require other parts of `Paste -`_, and is distributed as a separate package. +`_, and is distributed as a separate package. To see updates that have been made to Paste Deploy see the :doc:`news file `_. -- cgit v1.2.1 From 70a7ccdc10ea553e8736539a39d2c65f2a23c1f6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 10:43:08 -0800 Subject: Remove link to paste.urlmap --- docs/index.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2ef8f07..e38d104 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,9 +120,7 @@ section (``[app:main]``) and a server section (``[server:main]``). ``[composite:...]`` signifies something that dispatches to multiple applications (example below). -Here's a typical configuration file that also shows off mounting -multiple applications using `paste.urlmap -`_: +Here's a typical configuration file that also shows off mounting multiple applications: .. code-block:: ini -- cgit v1.2.1 From e15e1b9bca65dff73f11d0d4a31005f2c4d52e80 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 10:43:18 -0800 Subject: fix spelling --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index e38d104..3ef0254 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -87,7 +87,7 @@ checkout. You can also simply install ``PasteDeploy==dev``. For downloads and other information see the `PyPI PasteDeploy page `_. -A complimentary package is `Paste Script `_. +A complementary package is `Paste Script `_. To install that, use ``pip install PasteScript`` (or ``pip install PasteScript==dev``). From the User Perspective -- cgit v1.2.1 From 3c8dfafd4797ac889f233f45d45af8380f45d15f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 11:13:17 -0800 Subject: fix link to paster serve --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 3ef0254..adcb559 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -101,7 +101,7 @@ The primary interaction with Paste Deploy is through its configuration files. The primary thing you want to do with a configuration file is serve it. To learn about serving configuration files, see `the ``paster serve`` command -`_. +`_. The Config File ~~~~~~~~~~~~~~~ -- cgit v1.2.1 From d5281ff3b038bbe86b07b458a1f4eb669661180e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 16:49:53 -0800 Subject: missed one code-block highlighting --- docs/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index adcb559..d4e6b46 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -234,7 +234,9 @@ Python frameworks now support WSGI, so applications written for these frameworks should be usable. The primary function is ``paste.deploy.loadapp``. This loads an -application given a URI. You can use it like:: +application given a URI. You can use it like: + +.. code-block:: ini from paste.deploy import loadapp wsgi_app = loadapp('config:/path/to/config.ini') -- cgit v1.2.1 From 1539e73acb8c50f8ec987e12e6014ec7cab013bc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 16:50:44 -0800 Subject: use proper link syntax --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index d4e6b46..929b78b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,7 +37,7 @@ its container. Paste Deployment currently does not require other parts of `Paste `_, and is distributed as a separate package. -To see updates that have been made to Paste Deploy see the :doc:`news file `_. +To see updates that have been made to Paste Deploy see the :doc:`news file `. Paste Deploy is released under the `MIT license `_. -- cgit v1.2.1 From 2f1ef79953dfa6e0c7e898467d1a2d6cb026db5f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 16:53:03 -0800 Subject: comment out static directory via html_static_path --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 8ac46d7..00d8761 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -97,7 +97,7 @@ html_theme_options = dict( # 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'] +# html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -- cgit v1.2.1 From 7819a9f9579139bace88b3f7a06bfac3583493d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 27 Nov 2018 16:56:10 -0800 Subject: add docs env to tox --- tox.ini | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 9800db2..7819491 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,6 @@ [tox] -envlist = py27, py34, py35, py36, py37, pypy, pypy3 +envlist = py27, py34, py35, py36, py37, pypy, pypy3, + docs [testenv] deps = @@ -9,3 +10,12 @@ deps = pytest-cov commands = py.test --cov=paste/deploy --cov-report=xml --cov-report=html --cov-report=term-missing {posargs} + +[testenv:docs] +# pin to 3.5 to match what RTD uses +basepython = python3.5 +whitelist_externals = make +commands = + make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E" +extras = + docs -- cgit v1.2.1