From a821ec1147135752119ce443d22dae0a31d3abd8 Mon Sep 17 00:00:00 2001 From: Jason Madden Date: Tue, 10 Apr 2018 10:39:11 -0500 Subject: [PATCH] Clean up the configuring-your-application document. Move plone to the end instead of the beginning. Document how to use a configuration string instead of a file. Better links to ZConfig, repoze.zodbconn, and the ZODB.config functions. [skip ci] --- doc/conf.py | 9 +- doc/configure-application.rst | 169 ++++++++++++++++++++-------------- doc/generate_rst.py | 5 +- 3 files changed, 110 insertions(+), 73 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 9ceeeb7..ec959bf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -73,7 +73,7 @@ master_doc = 'index' # General information about the project. project = u'RelStorage' -copyright = u'2016, RelStorage contributors' +copyright = u'2016-2018, RelStorage contributors' author = u'RelStorage contributors' # The version info for the project you're documenting, acts as replacement for @@ -363,8 +363,11 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None, - 'http://zodb.readthedocs.io/en/latest/': None} +intersphinx_mapping = { + 'https://docs.python.org/': None, + 'http://www.zodb.org/en/latest/': None, + 'https://zconfig.readthedocs.io/en/latest/': None, +} extlinks = {'issue': ('https://github.com/zodb/relstorage/issues/%s', 'issue #'), diff --git a/doc/configure-application.rst b/doc/configure-application.rst index 5efd8be..27a2269 100644 --- a/doc/configure-application.rst +++ b/doc/configure-application.rst @@ -8,65 +8,29 @@ RelStorage, it's time to configure the application to use RelStorage. This means telling RelStorage about the database to use, how to connect to it, and specifying any additional options. -.. note:: This is just a quick-start guide. There is a :doc:`full list - of supported options ` in a separate - document, as well as a :doc:`list of database-specific - options `. +.. note:: + This is just a quick-start guide. There is a :doc:`full list of + supported options ` in a separate document, as + well as a :doc:`list of database-specific options + `. .. highlight:: guess -Configuring Plone -================= - -Plone uses the `plone.recipe.zope2instance`_ Buildout recipe to -generate zope.conf, so the easiest way to configure RelStorage in a -Plone site is to set the ``rel-storage`` parameter in ``buildout.cfg``. -The ``rel-storage`` parameter contains options separated by newlines, -with these values: - - * ``type``: any database type supported (``postgresql``, ``mysql``, - or ``oracle``) - * RelStorage options like ``cache-servers`` and ``poll-interval`` - * Adapter-specific options - -An example:: - - rel-storage = - type mysql - db plone - user plone - passwd PASSWORD - -You'll also need to make sure that the correct version of RelStorage -and its database drivers are installed (typically by adding them to -the ``[eggs]`` section in the ``buildout.cfg``). - -.. note:: For a detailed walk through of installing historic versions - of RelStorage in historic versions of Plone 3, see `this blog - post - `_. - It's important to note that this information is not directly - applicable to newer versions (Plone 4 does not use fake eggs, - and the version of ZODB used by Plone 4, 3.9.5 and above, - does not need patched). The comments section may contain - further hints for newer versions. - -.. _plone.recipe.zope2instance: https://pypi.python.org/pypi/plone.recipe.zope2instance Configuring using ZConfig ========================= The most common way to configure RelStorage will involve writing a -configuration file using the `ZConfig -`_ -syntax. You will write a ```` element containing -the general RelStorage options, and containing one database-specific -element (````, ```` or ````). (Where in the -file the ```` element goes is specific to the framework -or application you're using and will be covered next.) +configuration document (a file or string) using the `ZConfig +`_ syntax. You will write a +```` element containing the general RelStorage options, +and containing one database-specific element (````, +```` or ````). (Where in the document the ```` +element goes is specific to the framework or application you're using +and will be covered next.) In all cases, you'll need to add ``%import relstorage`` to the -top-level of the file to let ZConfig know about the RelStorage +top-level of the file to let :mod:`ZConfig` know about the RelStorage specific elements. @@ -110,8 +74,42 @@ where to store the blobs. For example:: -Configuring Zope 2 ------------------- +Without a Framework +------------------- + +You can manually open a ZODB database in Python code. Once you +have a configuration file as outlined above, you can use the +:func:`ZODB.config.databaseFromURL` API to get a ZODB database:: + + path = "path/to/configuration" + import ZODB.config + db = ZODB.config.databaseFromURL(path) + conn = db.open() + ... + +You can also skip the file and use a string with +:func:`ZODB.config.databaseFromString`:: + + conf = """ + %%import relstorage + + + + db %s + user %s + passwd %s + + + + """ % (dbname, user, passwd) + + db = ZODB.config.databaseFromString(conf) + conn = db.open() + ... + + +With Zope 2 +----------- To integrate RelStorage in Zope 2, specify a RelStorage backend in ``etc/zope.conf``. Remove the main mount point replace it with the @@ -128,12 +126,14 @@ To integrate RelStorage in Zope 2, specify a RelStorage backend in -Configuring ``repoze.zodbconn`` -------------------------------- +With ``repoze.zodbconn`` +------------------------ -To use RelStorage with ``repoze.zodbconn``, a package that makes ZODB -available to WSGI applications, create a configuration file with -contents similar to the following:: +To use RelStorage with `repoze.zodbconn +`_, a library that generically +creates a ZODB DB given a URI and which has special support for WSGI +applications, create a configuration file with contents similar to the +following:: %import relstorage @@ -145,20 +145,51 @@ contents similar to the following:: cache-size 100000 -``repoze.zodbconn`` expects a ZODB URI. Use a URI of the form -``zconfig://path/to/configuration#main`` where +``repoze.zodbconn`` expects a `ZConfig URI +`_. Use a +URI of the form ``zconfig://path/to/configuration#main`` where ``path/to/configuration`` is the complete path to the configuration -file, and ``main`` is the name given to the ```` element. +file, and ``main`` is the name given to the ```` element:: -Manually Opening a Database ---------------------------- + from repoze.zodbconn.uri import db_from_uri + db = db_from_uri('zconfig://path/to/configuration#main') -You can also manually open a ZODB database in Python code. Once you -have a configuration file as outlined above, you can use the -``ZODB.config.databaseFromURL`` API to get a ZODB database:: - path = "path/to/configuration" - import ZODB.config - db = ZODB.config.databaseFromURL(path) - conn = db.open() - ... +Configuring Plone +================= + +Plone uses the `plone.recipe.zope2instance`_ Buildout recipe to +generate zope.conf, so the easiest way to configure RelStorage in a +Plone site is to set the ``rel-storage`` parameter in ``buildout.cfg``. +The ``rel-storage`` parameter contains options separated by newlines, +with these values: + + * ``type``: any database type supported (``postgresql``, ``mysql``, + or ``oracle``) + * RelStorage options like ``cache-servers`` and ``poll-interval`` + * Adapter-specific options + +An example:: + + rel-storage = + type mysql + db plone + user plone + passwd PASSWORD + +You'll also need to make sure that the correct version of RelStorage +and its database drivers are installed (typically by adding them to +the ``[eggs]`` section in the ``buildout.cfg``). + +.. note:: + + For a detailed walk through of installing historic versions of + RelStorage in historic versions of Plone 3, see `this blog post + `_. + It's important to note that this information is not directly + applicable to newer versions (Plone 4 does not use fake eggs, and + the version of ZODB used by Plone 4, 3.9.5 and above, does not need + patched). The comments section may contain further hints for newer + versions. + +.. _plone.recipe.zope2instance: https://pypi.python.org/pypi/plone.recipe.zope2instance diff --git a/doc/generate_rst.py b/doc/generate_rst.py index 9fed4c6..022ef37 100755 --- a/doc/generate_rst.py +++ b/doc/generate_rst.py @@ -102,7 +102,10 @@ def generate_rst(do=True): assert os.path.exists('contents.rst'), 'Wrong directory, contents.rst not found' for module in modules: if module not in SKIP: - generate_rst_for_module(module, do=do) + try: + generate_rst_for_module(module, do=do) + except AttributeError as e: + print("Failed to generate rst for", module, e, "; skipping") def iter_autogenerated():