Merge pull request #17025 from ceph/wip-doc-warnings

fix sphinx build warnings and errors

Reviewed-by: Dan Mick <dmick@redhat.com>
Reviewed-by: Andrew Schoen <aschoen@redhat.com>

admin/build-doc

@@ -111,8 +111,11 @@ for target in $sphinx_targets; do
             extra_opt="-t man"
             ;;
     esac
-    $vdir/bin/sphinx-build -a -b $builder $extra_opt -d doctrees \
+    # Build with -W so that warnings are treated as errors and this fails
+    $vdir/bin/sphinx-build -W -a -b $builder $extra_opt -d doctrees \
                            $TOPDIR/doc $TOPDIR/build-doc/output/$target
+
+
 done
 
 #

admin/doc-requirements.txt

@@ -1,3 +1,3 @@
-Sphinx == 1.1.3
+Sphinx == 1.6.3
 -e git+https://github.com/ceph/sphinx-ditaa.git#egg=sphinx-ditaa
 -e git+https://github.com/michaeljones/breathe#egg=breathe

doc/cephfs/health-messages.rst

@@ -1,4 +1,6 @@
 
+.. _cephfs-health-messages:
+
 ======================
 CephFS health messages
 ======================

doc/conf.py

@@ -11,16 +11,20 @@
 master_doc = 'index'
 exclude_patterns = ['**/.#*', '**/*~', 'start/quick-common.rst']
 if tags.has('man'):
-    exclude_patterns += ['architecture.rst', 'glossary.rst', 'release*.rst',
+    master_doc = 'man_index'
+    exclude_patterns += ['index.rst', 'architecture.rst', 'glossary.rst', 'release*.rst',
                          'api/*',
                          'cephfs/*',
                          'dev/*',
                          'install/*',
                          'mon/*',
                          'rados/*',
+                         'mgr/*',
                          'radosgw/*',
                          'rbd/*',
                          'start/*']
+else:
+    exclude_patterns += ['man_index.rst']
 
 pygments_style = 'sphinx'
 

doc/dev/logging.rst

@@ -74,7 +74,7 @@ internal structures if they are the direct subject of the message,
 for example in a corruption, but use plain english.
 Example: instead of "Objecter requests" say "OSD client requests"
 Example: it is okay to mention internal structure in the context
-        of "Corrupt session table" (but don't say "Corrupt SessionTable")
+of "Corrupt session table" (but don't say "Corrupt SessionTable")
 
 Where possible, describe the consequence for system availability, rather
 than only describing the underlying state.  For example, rather than

doc/index.rst

@@ -3,7 +3,7 @@
 =================
 
 Ceph uniquely delivers **object, block, and file storage in one unified
-system**. 
+system**.
 
 .. raw:: html
 
@@ -21,7 +21,7 @@ system**.
 - Multi-site deployment
 - Multi-site replication
 
-.. raw:: html 
+.. raw:: html
 
 	</td><td><h3>Ceph Block Device</h3>
 
@@ -38,10 +38,10 @@ system**.
 - Incremental backup
 - Disaster recovery (multisite asynchronous replication)
 
-.. raw:: html 
+.. raw:: html
 
 	</td><td><h3>Ceph Filesystem</h3>
-	
+
 - POSIX-compliant semantics
 - Separates metadata from data
 - Dynamic rebalancing
@@ -55,22 +55,22 @@ system**.
 .. raw:: html
 
 	</td></tr><tr><td>
-	
+
 See `Ceph Object Store`_ for additional details.
 
 .. raw:: html
 
 	</td><td>
-	
+
 See `Ceph Block Device`_ for additional details.
-	
+
 .. raw:: html
 
 	</td><td>
-	
-See `Ceph Filesystem`_ for additional details.	
-	
-.. raw::	html 
+
+See `Ceph Filesystem`_ for additional details.
+
+.. raw::	html
 
 	</td></tr></tbody></table>
 
@@ -88,7 +88,7 @@ about Ceph, see our `Architecture`_ section.
 .. _Architecture: architecture
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :hidden:
 
    start/intro

doc/man_index.rst

@@ -0,0 +1,43 @@
+.. this is the man index/toctree reference. It is separate from the "regular"
+.. index so that it doesn't include things that are not tagged for man pages
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   man/8/ceph-authtool
+   man/8/ceph-clsinfo
+   man/8/ceph-conf
+   man/8/ceph-create-keys
+   man/8/ceph-debugpack
+   man/8/ceph-dencoder
+   man/8/ceph-deploy
+   man/8/ceph-detect-init
+   man/8/ceph-disk
+   man/8/ceph-fuse
+   man/8/ceph-mds
+   man/8/ceph-mon
+   man/8/ceph-osd
+   man/8/ceph-post-file
+   man/8/ceph-rbdnamer
+   man/8/ceph-rest-api
+   man/8/ceph-run
+   man/8/ceph-syn
+   man/8/ceph
+   man/8/crushtool
+   man/8/librados-config
+   man/8/monmaptool
+   man/8/mount.ceph
+   man/8/osdmaptool
+   man/8/rados
+   man/8/radosgw-admin
+   man/8/radosgw
+   man/8/rbd-fuse
+   man/8/rbd-ggate
+   man/8/rbd-mirror
+   man/8/rbd-nbd
+   man/8/rbd-replay-many
+   man/8/rbd-replay-prep
+   man/8/rbd-replay
+   man/8/rbd
+   man/8/rbdmap

doc/rados/api/python.rst

@@ -15,14 +15,14 @@ Getting Started
 
 You can create your own Ceph client using Python. The following tutorial will
 show you how to import the Ceph Python module, connect to a Ceph cluster,  and
-perform object operations as a ``client.admin`` user. 
+perform object operations as a ``client.admin`` user.
 
-.. note:: To use the Ceph Python bindings, you must have access to a 
+.. note:: To use the Ceph Python bindings, you must have access to a
    running Ceph cluster. To set one up quickly, see `Getting Started`_.
 
 First, create a Python source file for your Ceph client. ::
    :linenos:
-   
+
 	sudo vim client.py
 
 
@@ -54,21 +54,21 @@ of the initial Ceph monitors.
    :linenos:
 
 	import rados, sys
-	
+
 	#Create Handle Examples.
 	cluster = rados.Rados(conffile='ceph.conf')
 	cluster = rados.Rados(conffile=sys.argv[1])
 	cluster = rados.Rados(conffile = 'ceph.conf', conf = dict (keyring = '/path/to/keyring'))
 
 Ensure that the ``conffile`` argument provides the path and file name of your
 Ceph configuration file. You may use the ``sys`` module to avoid hard-coding the
-Ceph configuration path and file name. 
+Ceph configuration path and file name.
 
 Your Python client also requires a client keyring. For this example, we use the
 ``client.admin`` key by default. If you would like to specify the keyring when
 creating the cluster handle, you may use the ``conf`` argument. Alternatively,
-you may specify the keyring path in your Ceph configuration file. For example, 
-you may add something like the following line to you Ceph configuration file:: 
+you may specify the keyring path in your Ceph configuration file. For example,
+you may add something like the following line to you Ceph configuration file::
 
 	keyring = /path/to/ceph.client.admin.keyring
 
@@ -78,7 +78,7 @@ For additional details on modifying your configuration via Python, see `Configur
 Connect to the Cluster
 ----------------------
 
-Once you have a cluster handle configured, you may connect to the cluster. 
+Once you have a cluster handle configured, you may connect to the cluster.
 With a connection to the cluster, you may execute methods that return
 information about the cluster.
 
@@ -87,11 +87,11 @@ information about the cluster.
    :emphasize-lines: 7
 
 	import rados, sys
-	
+
 	cluster = rados.Rados(conffile='ceph.conf')
 	print "\nlibrados version: " + str(cluster.version())
-	print "Will attempt to connect to: " + str(cluster.conf_get('mon initial members'))	
-	
+	print "Will attempt to connect to: " + str(cluster.conf_get('mon initial members'))
+
 	cluster.connect()
 	print "\nCluster ID: " + cluster.get_fsid()
 
@@ -112,7 +112,7 @@ configuration file example uses the ``client.admin`` keyring you generated with
 
 .. code-block:: ini
    :linenos:
-   
+
 	[global]
 	...
 	keyring=/path/to/keyring/ceph.client.admin.keyring
@@ -123,7 +123,7 @@ Manage Pools
 
 When connected to the cluster, the ``Rados`` API allows you to manage pools. You
 can list pools, check for the existence of a pool, create a pool and delete a
-pool. 
+pool.
 
 .. code-block:: python
    :linenos:
@@ -174,7 +174,7 @@ to use.
 
 Once you have an I/O context, you can read/write objects, extended attributes,
 and perform a number of other operations. After you complete operations, ensure
-that you close the connection. For example: 
+that you close the connection. For example:
 
 .. code-block:: python
    :linenos:
@@ -190,18 +190,18 @@ Once you create an I/O context, you can write objects to the cluster. If you
 write to an object that doesn't exist, Ceph creates it. If you write to an
 object that exists, Ceph overwrites it (except when you specify a range, and
 then it only overwrites the range). You may read objects (and object ranges)
-from the cluster. You may also remove objects from the cluster. For example: 
+from the cluster. You may also remove objects from the cluster. For example:
 
 .. code-block:: python
 	:linenos:
 	:emphasize-lines: 2, 5, 8
-	
+
 	print "\nWriting object 'hw' with contents 'Hello World!' to pool 'data'."
 	ioctx.write_full("hw", "Hello World!")
 
 	print "\n\nContents of object 'hw'\n------------------------\n"
 	print ioctx.read("hw")
-	
+
 	print "\nRemoving object 'hw'"
 	ioctx.remove_object("hw")
 
@@ -210,7 +210,7 @@ Writing and Reading XATTRS
 --------------------------
 
 Once you create an object, you can write extended attributes (XATTRs) to
-the object and read XATTRs from the object. For example: 
+the object and read XATTRs from the object. For example:
 
 .. code-block:: python
 	:linenos:
@@ -226,7 +226,7 @@ the object and read XATTRs from the object. For example:
 Listing Objects
 ---------------
 
-If you want to examine the list of objects in a pool, you may 
+If you want to examine the list of objects in a pool, you may
 retrieve the list of objects and iterate over them with the object iterator.
 For example:
 
@@ -236,12 +236,12 @@ For example:
 
 	object_iterator = ioctx.list_objects()
 
-	while True : 
-	
-		try : 
+	while True :
+
+		try :
 			rados_object = object_iterator.next()
 			print "Object contents = " + rados_object.read()
-	
+
 		except StopIteration :
 			break
 
@@ -260,7 +260,7 @@ Configuration
 -------------
 
 The ``Rados`` class provides methods for getting and setting configuration
-values, reading the Ceph configuration file, and parsing arguments. You 
+values, reading the Ceph configuration file, and parsing arguments. You
 do not need to be connected to the Ceph Storage Cluster to invoke the following
 methods. See `Storage Cluster Configuration`_ for details on settings.
 
@@ -269,7 +269,7 @@ methods. See `Storage Cluster Configuration`_ for details on settings.
 .. automethod:: Rados.conf_set(option, val)
 .. automethod:: Rados.conf_read_file(path=None)
 .. automethod:: Rados.conf_parse_argv(args)
-.. automethod:: Rados.version()   
+.. automethod:: Rados.version()
 
 
 Connection Management
@@ -280,12 +280,22 @@ the cluster ``fsid``, retrieve cluster statistics, and disconnect (shutdown)
 from the cluster. You may also assert that the cluster handle is in a particular
 state (e.g., "configuring", "connecting", etc.).
 
-
 .. automethod:: Rados.connect(timeout=0)
 .. automethod:: Rados.shutdown()
 .. automethod:: Rados.get_fsid()
 .. automethod:: Rados.get_cluster_stats()
-.. automethod:: Rados.require_state(*args)
+
+.. documented manually because it raises warnings because of *args usage in the
+.. signature
+
+.. py:class:: Rados
+
+   .. py:method:: require_state(*args)
+
+      Checks if the Rados object is in a special state
+
+      :param args: Any number of states to check as separate arguments
+      :raises: :class:`RadosStateError`
 
 
 Pool Operations
@@ -307,8 +317,8 @@ Input/Output Context API
 
 To write data to and read data from the Ceph Object Store, you must create
 an Input/Output context (ioctx). The `Rados` class provides a `open_ioctx()`
-method. The remaining ``ioctx`` operations involve invoking methods of the 
-`Ioctx` and other classes. 
+method. The remaining ``ioctx`` operations involve invoking methods of the
+`Ioctx` and other classes.
 
 .. automethod:: Rados.open_ioctx(ioctx_name)
 .. automethod:: Ioctx.require_ioctx_open()
@@ -322,7 +332,7 @@ method. The remaining ``ioctx`` operations involve invoking methods of the
 .. --------------
 
 .. The Ceph Storage Cluster allows you to make a snapshot of a pool's state.
-.. Whereas, basic pool operations only require a connection to the cluster, 
+.. Whereas, basic pool operations only require a connection to the cluster,
 .. snapshots require an I/O context.
 
 .. Ioctx.create_snap(self, snap_name)