openstack/swift
Code Issues Proposed changes

PDF Documentation Build tox target

Browse Source 
This patch adds a `pdf-docs` tox target that will build
PDF versions of our docs. As per the Train community goal:

  https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.html

Add sphinxcontrib-svg2pdfconverter to doc/requirements.txt
to convert our SVGs.

Story: 2006122
Task: 35515
Change-Id: I26cefda80d3234df68d7152b404e0a71da74ab90
This commit is contained in:
Matthew Oliver 2019-09-04 14:30:33 +10:00 committed by Tim Burke
parent 4bd9003221
commit 0217b12b6d
6 changed files with 55 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/requirements.txt
View File

@ -8,3 +8,4 @@ openstackdocstheme>=1.30.0 # Apache-2.0
reno>=1.8.0 # Apache-2.0 reno>=1.8.0 # Apache-2.0
os-api-ref>=1.0.0 # Apache-2.0 os-api-ref>=1.0.0 # Apache-2.0
python-keystoneclient!=2.1.0,>=2.0.0 # Apache-2.0 python-keystoneclient!=2.1.0,>=2.0.0 # Apache-2.0
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

7
doc/source/conf.py
View File

@ -55,7 +55,8 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.coverage', 'sphinx.ext.coverage',
'sphinx.ext.ifconfig', 'sphinx.ext.ifconfig',
'openstackdocstheme'] 'openstackdocstheme',
'sphinxcontrib.rsvgconverter']
todo_include_todos = True todo_include_todos = True
# Add any paths that contain templates here, relative to this directory. # 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 # (source start file, target name, title, author, documentclass
# [howto/manual]). # [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'Swift.tex', u'Swift Documentation', ('index', 'doc-swift.tex', u'Swift Documentation',
u'Swift Team', 'manual'), u'Swift Team', 'manual'),
] ]
@ -244,6 +245,8 @@ latex_documents = [
# If false, no module index is generated. # If false, no module index is generated.
# latex_use_modindex = True # latex_use_modindex = True
latex_use_xindy = False
# -- Options for openstackdocstheme ------------------------------------------- # -- Options for openstackdocstheme -------------------------------------------
repository_name = 'openstack/swift' repository_name = 'openstack/swift'
bug_project = 'swift' bug_project = 'swift'

2
doc/source/index.rst
View File

@ -33,7 +33,7 @@ be found on the `OpenStack wiki`_ and at http://docs.openstack.org.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
getting_started getting_started

24
doc/source/overview_acl.rst
View File

@ -75,17 +75,17 @@ of ``.rlistings``, an error will occur if used with
============================== ================================================ ============================== ================================================
Element Description 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. required in the request.
``.r:<referrer>`` The referrer is granted access to objects. The .r:<referrer> The referrer is granted access to objects. The
referrer is identified by the ``Referer`` referrer is identified by the ``Referer``
request header in the request. No token is request header in the request. No token is
required. required.
``.r:-<referrer>`` This syntax (with "-" prepended to the .r:-<referrer> This syntax (with "-" prepended to the
referrer) is supported. However, it does not referrer) is supported. However, it does not
deny access if another element (e.g., ``.r:*``) deny access if another element (e.g., ``.r:*``)
grants access. 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 on the container provided the user also has
read access on objects (e.g., also has ``.r:*`` read access on objects (e.g., also has ``.r:*``
or ``.r:<referrer>``. No token is required. or ``.r:<referrer>``. No token is required.
@ -106,22 +106,22 @@ to take effect.
============================== ================================================ ============================== ================================================
Element Description Element Description
============================== ================================================ ============================== ================================================
``<project-id>:<user-id>`` The specified user, provided a token <project-id>:<user-id> The specified user, provided a token
scoped to the project is included scoped to the project is included
in the request, is granted access. in the request, is granted access.
Access to the container is also granted Access to the container is also granted
when used in ``X-Container-Read``. when used in ``X-Container-Read``.
``<project-id>:*`` Any user with a role in the specified Keystone <project-id>:\* Any user with a role in the specified Keystone
project has access. A token scoped to the project has access. A token scoped to the
project must be included in the request. project must be included in the request.
Access to the container is also granted Access to the container is also granted
when used in ``X-Container-Read``. when used in ``X-Container-Read``.
``*:<user-id>`` The specified user has access. A token \*:<user-id> The specified user has access. A token
for the user (scoped to any for the user (scoped to any
project) must be included in the request. project) must be included in the request.
Access to the container is also granted Access to the container is also granted
when used in ``X-Container-Read``. when used in ``X-Container-Read``.
``*:*`` Any user has access. \*:\* Any user has access.
Access to the container is also granted Access to the container is also granted
when used in ``X-Container-Read``. when used in ``X-Container-Read``.
The ``*:*`` element differs from the ``.r:*`` The ``*:*`` element differs from the ``.r:*``
@ -131,7 +131,7 @@ Element Description
does not require a token. In addition, does not require a token. In addition,
``.r:*`` does not grant access to the ``.r:*`` does not grant access to the
container listing. container listing.
``<role_name>`` A user with the specified role *name* on the <role_name> A user with the specified role *name* on the
project within which the container is stored is project within which the container is stored is
granted access. A user token scoped to the granted access. A user token scoped to the
project must be included in the request. Access project must be included in the request. Access
@ -142,7 +142,7 @@ Element Description
.. note:: .. note::
Keystone project (tenant) or user *names* (i.e., Keystone project (tenant) or user *names* (i.e.,
``<project-name>:<user-name``) must no longer be ``<project-name>:<user-name>``) must no longer be
used because with the introduction used because with the introduction
of domains in Keystone, names are not globally unique. You should of domains in Keystone, names are not globally unique. You should
use user and project *ids* instead. use user and project *ids* instead.
@ -167,7 +167,7 @@ the elements described in :ref:`acl_common_elements`.
============================== ================================================ ============================== ================================================
Element Description Element Description
============================== ================================================ ============================== ================================================
``<user-name>`` The named user is granted access. The <user-name> The named user is granted access. The
wildcard ("*") character is not supported. wildcard ("*") character is not supported.
A token from the user must be included in the A token from the user must be included in the
request. 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 For more details, see :mod:`swift.common.middleware.tempauth`. For details
on the ACL format, see :mod:`swift.common.middleware.acl`. on the ACL format, see :mod:`swift.common.middleware.acl`.

51
doc/source/overview_ring.rst
View File

@ -82,30 +82,33 @@ List of Devices
The list of devices is known internally to the Ring class as ``devs``. Each 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: item in the list of devices is a dictionary with the following keys:
====== ======= ============================================================== .. table::
id integer The index into the list of devices. :widths: 10 10 80
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 id integer The index into the list of devices.
devices. This usually corresponds directly to the amount of zone integer The zone in which the device resides.
disk space the device has compared to other devices. For region integer The region in which the zone resides.
instance a device with 1 terabyte of space might have a weight weight float The relative weight of the device in comparison to other
of 100.0 and another device with 2 terabytes of space might devices. This usually corresponds directly to the amount of
have a weight of 200.0. This weight can also be used to bring disk space the device has compared to other devices. For
back into balance a device that has ended up with more or less instance a device with 1 terabyte of space might have a weight
data than desired over time. A good average weight of 100.0 of 100.0 and another device with 2 terabytes of space might
allows flexibility in lowering the weight later if necessary. have a weight of 200.0. This weight can also be used to bring
ip string The IP address or hostname of the server containing the device. back into balance a device that has ended up with more or less
port int The TCP port on which the server process listens to serve data than desired over time. A good average weight of 100.0
requests for the device. allows flexibility in lowering the weight later if necessary.
device string The on-disk name of the device on the server. ip string The IP address or hostname of the server containing the device.
For example: ``sdb1`` port int The TCP port on which the server process listens to serve
meta string A general-use field for storing additional information for the requests for the device.
device. This information isn't used directly by the server device string The on-disk name of the device on the server.
processes, but can be useful in debugging. For example, the For example: ``sdb1``
date and time of installation and hardware manufacturer could meta string A general-use field for storing additional information for the
be stored here. 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:: .. note::
The list of devices may contain holes, or indexes set to ``None``, for The list of devices may contain holes, or indexes set to ``None``, for

9
tox.ini
View File

@ -149,3 +149,12 @@ deps =
-c{toxinidir}/lower-constraints.txt -c{toxinidir}/lower-constraints.txt
-r{toxinidir}/test-requirements.txt -r{toxinidir}/test-requirements.txt
-r{toxinidir}/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