diff --git a/doc/requirements.txt b/doc/requirements.txt index 7c23cdc00f..88f49c6636 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -8,3 +8,4 @@ openstackdocstheme>=1.30.0 # Apache-2.0 reno>=1.8.0 # Apache-2.0 os-api-ref>=1.0.0 # Apache-2.0 python-keystoneclient!=2.1.0,>=2.0.0 # Apache-2.0 +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 7b41b01e8e..3f048d68fd 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -55,7 +55,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', - 'openstackdocstheme'] + 'openstackdocstheme', + 'sphinxcontrib.rsvgconverter'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. @@ -223,7 +224,7 @@ htmlhelp_basename = 'swiftdoc' # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ - ('index', 'Swift.tex', u'Swift Documentation', + ('index', 'doc-swift.tex', u'Swift Documentation', u'Swift Team', 'manual'), ] @@ -244,6 +245,8 @@ latex_documents = [ # If false, no module index is generated. # latex_use_modindex = True +latex_use_xindy = False + # -- Options for openstackdocstheme ------------------------------------------- repository_name = 'openstack/swift' bug_project = 'swift' diff --git a/doc/source/index.rst b/doc/source/index.rst index 861b5e6c77..9d3023aac8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -33,7 +33,7 @@ be found on the `OpenStack wiki`_ and at http://docs.openstack.org. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 getting_started diff --git a/doc/source/overview_acl.rst b/doc/source/overview_acl.rst index 533245ff6c..d4c1ca09e2 100644 --- a/doc/source/overview_acl.rst +++ b/doc/source/overview_acl.rst @@ -75,17 +75,17 @@ of ``.rlistings``, an error will occur if used with ============================== ================================================ Element Description ============================== ================================================ -``.r:*`` Any user has access to objects. No token is +.r:* Any user has access to objects. No token is required in the request. -``.r:`` The referrer is granted access to objects. The +.r: The referrer is granted access to objects. The referrer is identified by the ``Referer`` request header in the request. No token is required. -``.r:-`` This syntax (with "-" prepended to the +.r:- This syntax (with "-" prepended to the referrer) is supported. However, it does not deny access if another element (e.g., ``.r:*``) grants access. -``.rlistings`` Any user can perform a HEAD or GET operation +.rlistings Any user can perform a HEAD or GET operation on the container provided the user also has read access on objects (e.g., also has ``.r:*`` or ``.r:``. No token is required. @@ -106,22 +106,22 @@ to take effect. ============================== ================================================ Element Description ============================== ================================================ -``:`` The specified user, provided a token +: The specified user, provided a token scoped to the project is included in the request, is granted access. Access to the container is also granted when used in ``X-Container-Read``. -``:*`` Any user with a role in the specified Keystone +:\* Any user with a role in the specified Keystone project has access. A token scoped to the project must be included in the request. Access to the container is also granted when used in ``X-Container-Read``. -``*:`` The specified user has access. A token +\*: The specified user has access. A token for the user (scoped to any project) must be included in the request. Access to the container is also granted when used in ``X-Container-Read``. -``*:*`` Any user has access. +\*:\* Any user has access. Access to the container is also granted when used in ``X-Container-Read``. The ``*:*`` element differs from the ``.r:*`` @@ -131,7 +131,7 @@ Element Description does not require a token. In addition, ``.r:*`` does not grant access to the container listing. -```` A user with the specified role *name* on the + A user with the specified role *name* on the project within which the container is stored is granted access. A user token scoped to the project must be included in the request. Access @@ -142,7 +142,7 @@ Element Description .. note:: Keystone project (tenant) or user *names* (i.e., - ``::``) must no longer be used because with the introduction of domains in Keystone, names are not globally unique. You should use user and project *ids* instead. @@ -167,7 +167,7 @@ the elements described in :ref:`acl_common_elements`. ============================== ================================================ Element Description ============================== ================================================ -```` The named user is granted access. The + The named user is granted access. The wildcard ("*") character is not supported. A token from the user must be included in the request. @@ -407,4 +407,4 @@ admin These identities have "swift_owner" privileges. A user with For more details, see :mod:`swift.common.middleware.tempauth`. For details -on the ACL format, see :mod:`swift.common.middleware.acl`. \ No newline at end of file +on the ACL format, see :mod:`swift.common.middleware.acl`. diff --git a/doc/source/overview_ring.rst b/doc/source/overview_ring.rst index 5d88013de4..d5415c2c7c 100644 --- a/doc/source/overview_ring.rst +++ b/doc/source/overview_ring.rst @@ -82,30 +82,33 @@ List of Devices The list of devices is known internally to the Ring class as ``devs``. Each item in the list of devices is a dictionary with the following keys: -====== ======= ============================================================== -id integer The index into the list of devices. -zone integer The zone in which the device resides. -region integer The region in which the zone resides. -weight float The relative weight of the device in comparison to other - devices. This usually corresponds directly to the amount of - disk space the device has compared to other devices. For - instance a device with 1 terabyte of space might have a weight - of 100.0 and another device with 2 terabytes of space might - have a weight of 200.0. This weight can also be used to bring - back into balance a device that has ended up with more or less - data than desired over time. A good average weight of 100.0 - allows flexibility in lowering the weight later if necessary. -ip string The IP address or hostname of the server containing the device. -port int The TCP port on which the server process listens to serve - requests for the device. -device string The on-disk name of the device on the server. - For example: ``sdb1`` -meta string A general-use field for storing additional information for the - device. This information isn't used directly by the server - processes, but can be useful in debugging. For example, the - date and time of installation and hardware manufacturer could - be stored here. -====== ======= ============================================================== +.. table:: + :widths: 10 10 80 + + ====== ======= ============================================================== + id integer The index into the list of devices. + zone integer The zone in which the device resides. + region integer The region in which the zone resides. + weight float The relative weight of the device in comparison to other + devices. This usually corresponds directly to the amount of + disk space the device has compared to other devices. For + instance a device with 1 terabyte of space might have a weight + of 100.0 and another device with 2 terabytes of space might + have a weight of 200.0. This weight can also be used to bring + back into balance a device that has ended up with more or less + data than desired over time. A good average weight of 100.0 + allows flexibility in lowering the weight later if necessary. + ip string The IP address or hostname of the server containing the device. + port int The TCP port on which the server process listens to serve + requests for the device. + device string The on-disk name of the device on the server. + For example: ``sdb1`` + meta string A general-use field for storing additional information for the + device. This information isn't used directly by the server + processes, but can be useful in debugging. For example, the + date and time of installation and hardware manufacturer could + be stored here. + ====== ======= ============================================================== .. note:: The list of devices may contain holes, or indexes set to ``None``, for diff --git a/tox.ini b/tox.ini index 7d25a6acde..8b559380d6 100644 --- a/tox.ini +++ b/tox.ini @@ -149,3 +149,12 @@ deps = -c{toxinidir}/lower-constraints.txt -r{toxinidir}/test-requirements.txt -r{toxinidir}/requirements.txt + +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf