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
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

7
doc/source/conf.py
View File

@ -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'

2
doc/source/index.rst
View File

@ -33,7 +33,7 @@ be found on the `OpenStack wiki`_ and at http://docs.openstack.org.
.. toctree::
:maxdepth: 1
:maxdepth: 2
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
============================== ================================================
``.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:<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``
request header in the request. No token is
required.
``.r:-<referrer>`` This syntax (with "-" prepended to the
.r:-<referrer> 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:<referrer>``. No token is required.
@ -106,22 +106,22 @@ to take effect.
============================== ================================================
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
in the request, is granted access.
Access to the container is also granted
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 must be included in the request.
Access to the container is also granted
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
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.
``<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
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.,
``<project-name>:<user-name``) must no longer be
``<project-name>:<user-name>``) 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
============================== ================================================
``<user-name>`` The named user is granted access. The
<user-name> 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`.
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
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

9
tox.ini
View File

@ -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