From 0435ccd15f7c7c3960208d0bac413cd8eb42cd56 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 6 Apr 2013 08:11:45 +0200 Subject: trim commented-out parts of docs/conf.py proposed here: https://groups.google.com/forum/?fromgroups=#!topic/pylons-devel/n2-7zvLWK3E --- docs/conf.py | 91 ++---------------------------------------------------------- 1 file changed, 2 insertions(+), 89 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 1ddcae08e..33bedc9dd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,39 +101,19 @@ release = version # Else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' -# List of documents that shouldn't be included in the build. -#unused_docs = [] - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_themes/README.rst', ] -# List of directories, relative to source directories, that shouldn't be searched -# for source files. -#exclude_dirs = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - # If true, the current module name will be prepended to all description # unit titles (such as .. function::). add_module_names = False -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - # The name of the Pygments (syntax highlighting) style to use. #pygments_style = book and 'bw' or 'tango' if book: pygments_style = 'bw' -# The default language to highlight source code in. -#highlight_language = 'guess' - # Options for HTML output # ----------------------- @@ -169,67 +149,15 @@ html_theme_options = dict( github_url='https://github.com/Pylons/pyramid', # in_progress='true', ) -# 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 = 'pyramid.css' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". html_title = 'The Pyramid Web Application Development Framework v%s' % release -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = 'Home' - -# The name of an image file (within the static path) to place at the top of -# the sidebar. -#html_logo = '_static/pyramid.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = '_static/pyramid.ico' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] - # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - # Output file base name for HTML help builder. htmlhelp_basename = 'pyramid' @@ -252,20 +180,10 @@ latex_documents = [ 'Chris McDonough', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = '_static/pylons_small.png' - # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. latex_use_parts = True -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - # If false, no module index is generated. latex_use_modindex = False @@ -508,13 +426,6 @@ epub_identifier = '0615445675' # A unique identification for the text. epub_uid = 'The Pyramid Web Application Development Framework, Version %s' \ % release -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] # A list of files that should not be packed into the epub file. epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', @@ -524,3 +435,5 @@ epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', # The depth of the table of contents in toc.ncx. epub_tocdepth = 3 + +# For a list of all settings, visit http://sphinx-doc.org/config.html. -- cgit v1.2.3 From 1f7a00346411033d935bf931c206b585353f8be4 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 5 Oct 2013 00:37:09 -0500 Subject: Docs: Link from renderer narrative docs to example render_to_response call, and index the example. More fully explain the 2 examples, one with render_to_response call and one without. --- docs/narr/introduction.rst | 11 +++++++++-- docs/narr/renderers.rst | 10 ++++++---- 2 files changed, 15 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 032f4be6b..8c2acf95c 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -321,7 +321,14 @@ assertion instead that the view returns "the right stuff" in the dictionary it returns. You can write "real" unit tests instead of functionally testing all of your views. -For example, instead of: +.. index:: + pair: renderer; explicitly calling + pair: view renderer; explictly calling + +.. _example_render_to_response_call: + +For example, instead of returning a ``Response`` object from a +``render_to_response`` call: .. code-block:: python :linenos: @@ -332,7 +339,7 @@ For example, instead of: return render_to_response('myapp:templates/mytemplate.pt', {'a':1}, request=request) -You can do this: +You can return a Python dictionary: .. code-block:: python :linenos: diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 4046c67fa..b86f7298b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -56,10 +56,12 @@ serialization techniques. In practice, renderers obtain application data values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. -View configuration can vary the renderer associated with a view callable via -the ``renderer`` attribute. For example, this call to -:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer -with a view callable: +View callables can :ref:`explicitly call +` renderers but, typically, view +configuration declares the renderer used to render a view callable's +results. This is done with the ``renderer`` attribute. For example, +this call to :meth:`~pyramid.config.Configurator.add_view` associates +the ``json`` renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From cabaa67149f95796aac35a19313ca543064a7a0b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 5 Oct 2013 00:56:39 -0500 Subject: Docs: project.rst: Hilight that dictionaries provide values to templates. --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9451f41b1..8788977c7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,6 +878,8 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. +.. note:: Dictionaries provide values to :term:`template`\s. + This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From a8cb84e04a81bcfd0236c3ff534919bb555e7ed3 Mon Sep 17 00:00:00 2001 From: BauhausSP Date: Sun, 6 Oct 2013 21:08:14 +0100 Subject: Fixed an example "from pyramid.view import view_config" instead of "from pyramid.view. import view_config" --- docs/narr/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index ca6dc565b..64343ca3e 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -150,7 +150,7 @@ do things the newer way: .. code-block:: python :linenos: - from pyramid.view. import view_config + from pyramid.view import view_config from pyramid.static import static_view myview = static_view('static', 'static', use_subpath=True) -- cgit v1.2.3 From 0f5e17a983ecb97bb0bdeb169ac775886c9e15fe Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:53:06 -0500 Subject: Docs: project.rst: Utilize sidebars for out-of-band text. --- docs/narr/project.rst | 58 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8788977c7..622f40d69 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -210,6 +210,12 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). +.. sidebar:: Verbose Testing + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + On UNIX: .. code-block:: text @@ -243,12 +249,6 @@ Here's sample output from a test run on UNIX: OK -.. note:: - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. @@ -684,6 +684,14 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. +.. sidebar:: Python's ``setup.py`` + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + .. index:: single: setup.py @@ -694,14 +702,6 @@ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing, packaging, and distributing your application. -.. note:: - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,6 +857,26 @@ and which returns a :term:`response`. :language: python :linenos: +.. sidebar:: Fully Interactive Development + + Because our ``development.ini`` has a ``pyramid.reload_templates = + true`` directive indicating that templates should be reloaded when + they change, you won't need to restart the application server to + see changes you make to templates. During development, this is + handy. If this directive had been ``false`` (or if the directive + did not exist), you would need to restart the application server + for each template change. For production applications, you should + set your project's ``pyramid.reload_templates`` to ``false`` to + increase template rendering speed. + + Pyramid can also dynamically reload changed Python files. For more + on this see :ref:`reloading_code` above. + + The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows + interactive access to traceback execution stack frames from the + Python interpreter. + Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). @@ -888,16 +908,6 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. - .. index:: single: static directory -- cgit v1.2.3 From 5276ce567b1c04e3d4cadcfb7f41b135296b1d39 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:55:07 -0500 Subject: Docs: project.rst: Move note that tempates get values from dictionaries down a paragraph. --- docs/narr/project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 622f40d69..fc1d473ac 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -898,13 +898,13 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries provide values to :term:`template`\s. - This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then returns the HTML in a :term:`response`. +.. note:: Dictionaries provide values to :term:`template`\s. + See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -- cgit v1.2.3 From daefb5f5009166ac9fbc3ba7fb6498d093620eec Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 10:12:14 -0500 Subject: Doc: introduction.rst: Broaden debug toolbar feature description to include other interactive development features. --- docs/narr/introduction.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 032f4be6b..64cce407a 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -176,8 +176,13 @@ static file server in production without changing any code. Example: :ref:`static_assets_section`. -Debug Toolbar -~~~~~~~~~~~~~ +Fully Interactive Development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When developing a Pyramid application a variety of interactive features are +available. Pyramid will automatically utilize changed templates when +rendering pages and automatically restart the application to incorporate +changed python code. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 6461f60320106b5114bb7f226959c7d7f2995ec2 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 11:26:22 -0500 Subject: Docs: introduction.rst: Improve wording. --- docs/narr/introduction.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 64cce407a..816199038 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -179,10 +179,10 @@ Example: :ref:`static_assets_section`. Fully Interactive Development ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When developing a Pyramid application a variety of interactive features are -available. Pyramid will automatically utilize changed templates when -rendering pages and automatically restart the application to incorporate -changed python code. +When developing a Pyramid application a variety of interactive +features are available. Pyramid can automatically utilize changed +templates when rendering pages and automatically restart the +application to incorporate changed python code. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 70b05dfaea547fea328a7054acd921f02be34a87 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:06:15 -0500 Subject: Docs: renders.rst: Use punctuation to make sentence simpler. --- docs/narr/renderers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b86f7298b..49f834ecb 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,7 +57,7 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call -` renderers but, typically, view +` renderers; but typically view configuration declares the renderer used to render a view callable's results. This is done with the ``renderer`` attribute. For example, this call to :meth:`~pyramid.config.Configurator.add_view` associates -- cgit v1.2.3 From 77497acef17d5e5996ac231bf8ac9b679b291316 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:10:18 -0500 Subject: Docs: renders.rst: Break sentence into two to simplify. --- docs/narr/renderers.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 49f834ecb..b542e42a2 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,11 +57,12 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call -` renderers; but typically view -configuration declares the renderer used to render a view callable's -results. This is done with the ``renderer`` attribute. For example, -this call to :meth:`~pyramid.config.Configurator.add_view` associates -the ``json`` renderer with a view callable: +` renderers, but they typically +don't. Instead view configuration declares the renderer used to +render a view callable's results. This is done with the ``renderer`` +attribute. For example, this call to +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` +renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From 0681d5798574d5f3ed644bf56086208c8571e0b9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:12:27 -0500 Subject: Docs: renders.rst: Make sentences short per IRC chat with committers. --- docs/narr/renderers.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b542e42a2..7c25386f5 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -56,13 +56,11 @@ serialization techniques. In practice, renderers obtain application data values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. -View callables can :ref:`explicitly call -` renderers, but they typically -don't. Instead view configuration declares the renderer used to -render a view callable's results. This is done with the ``renderer`` -attribute. For example, this call to -:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` -renderer with a view callable: +View callables can :ref:`explicitly call ` +renderers. Typically view configuration declares the renderer used to render +a view callable's results. This is done with the ``renderer`` attribute. +For example, this call to :meth:`~pyramid.config.Configurator.add_view` +associates the ``json`` renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From a26d09f291bdf4f9c7853b1dbfc9643a678a7b94 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 16:29:31 -0500 Subject: Docs: renders.rst: Make sentences that everybody's happy with. --- docs/narr/renderers.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 7c25386f5..740c81555 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -57,10 +57,11 @@ values from Python dictionaries so, in practice, view callables which use renderers return Python dictionaries. View callables can :ref:`explicitly call ` -renderers. Typically view configuration declares the renderer used to render -a view callable's results. This is done with the ``renderer`` attribute. -For example, this call to :meth:`~pyramid.config.Configurator.add_view` -associates the ``json`` renderer with a view callable: +renderers, but typically don't. Instead view configuration declares the +renderer used to render a view callable's results. This is done with the +``renderer`` attribute. For example, this call to +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` +renderer with a view callable: .. code-block:: python -- cgit v1.2.3 From 13cf2dd2c912c1961d429c8a5756622cf960d5bf Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 7 Oct 2013 19:14:49 -0500 Subject: fix some broken positional args to sqlalchemy models --- docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py | 2 +- docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py | 2 +- docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py | 2 +- docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) -- cgit v1.2.3 From 56170f30f6cd1d4268d9e5b0cd24a75c645ab0ca Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 21:00:26 -0500 Subject: Docs: project.rst: Reword template reload note per Steve Piercy's suggestions. Take care to retain the thought that the defaults setup by the scaffold cause automatic template reload. This patch should be applied before the docs_dict_note branch. --- docs/narr/project.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9451f41b1..0de46c806 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -886,15 +886,16 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. +.. note:: ``development.ini`` has a setting that controls how templates are + reloaded: ``pyramid.reload_templates``. + + - A setting of ``True`` (as in the scaffold ``development.ini``) + automatically reloads changed templates without a server restart. This + is convenient while developing but slows template rendering speed. + + - A setting of ``False`` (the default) requires a server restart to + integrate template changes. Production applications should set + ``pyramid.reload_templates = False``. .. index:: single: static directory -- cgit v1.2.3 From 8e1e6914945a5a3d05f49f0e32b7152182b23767 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 22:20:26 -0500 Subject: Docs: introduction.rst: Note that printf() works. --- docs/narr/introduction.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 9ec26f276..b60934ebb 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -182,7 +182,8 @@ Fully Interactive Development When developing a Pyramid application a variety of interactive features are available. Pyramid can automatically utilize changed templates when rendering pages and automatically restart the -application to incorporate changed python code. +application to incorporate changed python code. Plain old ``printf()`` +calls used for debugging can display to a console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and -- cgit v1.2.3 From 5ded35a5d057eb6188d6f80c47593ec934833d47 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:32:14 -0700 Subject: - straighten out difference between content and its presentation, re: admonitions of note, seealse, sidebar --- docs/narr/project.rst | 79 +++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 46 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4397c09b..fcce9fac4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -146,7 +146,7 @@ puts his projects in ``C:\projects``. .. warning:: - You’ll need to avoid using ``pcreate`` to create a project with the same + You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you should avoid using the names ``site`` or ``test``, both of which conflict with Python standard library packages. You should also avoid @@ -210,12 +210,6 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). -.. sidebar:: Verbose Testing - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - On UNIX: .. code-block:: text @@ -253,6 +247,12 @@ The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. +.. note:: + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + .. index:: single: running an application single: pserve @@ -684,14 +684,6 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. -.. sidebar:: Python's ``setup.py`` - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - .. index:: single: setup.py @@ -702,6 +694,14 @@ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing, packaging, and distributing your application. +.. note:: + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,26 +857,6 @@ and which returns a :term:`response`. :language: python :linenos: -.. sidebar:: Fully Interactive Development - - Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to - increase template rendering speed. - - Pyramid can also dynamically reload changed Python files. For more - on this see :ref:`reloading_code` above. - - The :ref:`debug_toolbar` provides interactive access to your - application's internals and, should an exception occur, allows - interactive access to traceback execution stack frames from the - Python interpreter. - Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). @@ -905,20 +885,27 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. -See :ref:`views_which_use_a_renderer` for more information about how views, -renderers, and templates relate and cooperate. - .. note:: ``development.ini`` has a setting that controls how templates are - reloaded: ``pyramid.reload_templates``. - - - A setting of ``True`` (as in the scaffold ``development.ini``) - automatically reloads changed templates without a server restart. This - is convenient while developing but slows template rendering speed. - - - A setting of ``False`` (the default) requires a server restart to - integrate template changes. Production applications should set + reloaded, ``pyramid.reload_templates``. + + - When set to ``True`` (as in the scaffold ``development.ini``) changed + templates automatically reload without a server restart. This is + convenient while developing, but slows template rendering speed. + + - When set to ``False`` (the default value), changing templates requires + a server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. +.. seealso:: See also :ref:`views_which_use_a_renderer` for more information + about how views, renderers, and templates relate and cooperate. + +.. seealso:: Pyramid can also dynamically reload changed Python files. For + more on this see :ref:`reloading_code`. + +.. seealso:: The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows interactive + access to traceback execution stack frames from the Python interpreter. + .. index:: single: static directory -- cgit v1.2.3 From d84407421d1830ed726bcc280b3de112aca701e7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:40:10 -0700 Subject: wrap to 79 --- docs/narr/introduction.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index b60934ebb..ece720a97 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -179,11 +179,11 @@ Example: :ref:`static_assets_section`. Fully Interactive Development ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When developing a Pyramid application a variety of interactive -features are available. Pyramid can automatically utilize changed -templates when rendering pages and automatically restart the -application to incorporate changed python code. Plain old ``printf()`` -calls used for debugging can display to a console. +When developing a Pyramid application, several interactive features are +available. Pyramid can automatically utilize changed templates when rendering +pages and automatically restart the application to incorporate changed python +code. Plain old ``printf()`` calls used for debugging can display to a +console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and @@ -790,7 +790,7 @@ automate some of the tedium away: for method in ('GET', 'POST', 'HEAD'): view = getattr(module, 'xhr_%s_view' % method, None) if view is not None: - config.add_view(view, route_name='xhr_route', xhr=True, + config.add_view(view, route_name='xhr_route', xhr=True, permission='view', request_method=method) config = Configurator() -- cgit v1.2.3 From 716bdf37573ee8ef295ac1d01a1e8ff96c4c0f43 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:55:30 -0700 Subject: - use clearer subject --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fcce9fac4..8b7c24725 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -984,9 +984,9 @@ named ``views`` instead of within a single ``views.py`` file, you might: can be empty. This just tells Python that the ``views`` directory is a *package*.) -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. Because the ``templates`` directory - remains in the ``myproject`` package, the template :term:`asset +- *Move* the content from the existing ``views.py`` file to a file inside the + new ``views`` directory named, say, ``blog.py``. Because the ``templates`` + directory remains in the ``myproject`` package, the template :term:`asset specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). -- cgit v1.2.3 From 6a3eed4ddc4178d19c0002ec72b9a1d6494e01ae Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 8 Oct 2013 00:40:15 -0700 Subject: - remove . from end of URL --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index f18cf3ec3..ec62faa99 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -458,4 +458,4 @@ epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', # The depth of the table of contents in toc.ncx. epub_tocdepth = 3 -# For a list of all settings, visit http://sphinx-doc.org/config.html. +# For a list of all settings, visit http://sphinx-doc.org/config.html -- cgit v1.2.3