doc/cephadm: use sphinx autoclass to document RGWSpec

Signed-off-by: Sebastian Wagner <sewagner@redhat.com>
(cherry picked from commit 8ef77a0bbcef710185c7ee6452d6ca8a133843c1)

diff --git a/doc/cephadm/services/index.rst b/doc/cephadm/services/index.rst
index 00eacdfce2f7e96001a823d44a04211a694886ae..f34180eb24fc6a9fe835eba87132b0990fb41fc0 100644 (file)
--- a/doc/cephadm/services/index.rst
+++ b/doc/cephadm/services/index.rst
@@ -99,28 +99,15 @@ deployment of services.  Here is an example of a service specification in YAML:
     unmanaged: false
     networks:
     - 192.169.142.0/24
-    ...
+    spec:
+      # Additional service specific attributes.
 
 In this example, the properties of this service specification are:
 
-* ``service_type``
-    The type of the service. Needs to be either a Ceph
-    service (``mon``, ``crash``, ``mds``, ``mgr``, ``osd`` or
-    ``rbd-mirror``), a gateway (``nfs`` or ``rgw``), part of the
-    monitoring stack (``alertmanager``, ``grafana``, ``node-exporter`` or
-    ``prometheus``) or (``container``) for custom containers.
-* ``service_id``
-    The name of the service.
-* ``placement``
-    See :ref:`orchestrator-cli-placement-spec`.
-* ``networks``: A list of network identities instructing the daemons to only bind
-    on the particular networks in that list. In case the cluster is distributed across multiple
-    networks, you can add multiple networks. See :ref:`cephadm-monitoring-networks-ports`, 
-    :ref:`cephadm-rgw-networks` and :ref:`cephadm-mgr-networks`.    
-* ``unmanaged`` If set to ``true``, the orchestrator will not deploy nor remove
-    any daemon associated with this service. Placement and all other properties
-    will be ignored. This is useful, if you do not want this service to be
-    managed temporarily. For cephadm, See :ref:`cephadm-spec-unmanaged`
+.. py:currentmodule:: ceph.deployment.service_spec
+
+.. autoclass:: ServiceSpec
+   :members:
 
 Each service type can have additional service-specific properties.
 

diff --git a/doc/cephadm/services/rgw.rst b/doc/cephadm/services/rgw.rst
index 2914042cc375bb8678ddcc5ea95864931edac67a..47017139b76c365c0e4dabe777ba08b2d3fed8c8 100644 (file)
--- a/doc/cephadm/services/rgw.rst
+++ b/doc/cephadm/services/rgw.rst
@@ -140,7 +140,15 @@ Then apply this yaml document:
   ceph orch apply -i myrgw.yaml
 
 Note the value of ``rgw_frontend_ssl_certificate`` is a literal string as
-indicated by a ``|`` character preserving newline characters. 
+indicated by a ``|`` character preserving newline characters.
+
+Service specification
+---------------------
+
+.. py:currentmodule:: ceph.deployment.service_spec
+
+.. autoclass:: RGWSpec
+   :members:
 
 .. _orchestrator-haproxy-service-spec:
 

diff --git a/doc/mgr/orchestrator_modules.rst b/doc/mgr/orchestrator_modules.rst
index 65e2e4981d1337c55531fa20788a31d52c08dac5..5991afe6136568c6aa197d449e585b516256c8e4 100644 (file)
--- a/doc/mgr/orchestrator_modules.rst
+++ b/doc/mgr/orchestrator_modules.rst
@@ -233,6 +233,9 @@ Services
 .. py:currentmodule:: ceph.deployment.service_spec
 
 .. autoclass:: ServiceSpec
+  :members:
+  :private-members:
+  :noindex:
 
 .. py:currentmodule:: orchestrator
 
@@ -291,6 +294,7 @@ Services
 .. py:currentmodule:: ceph.deployment.service_spec
 
 .. autoclass:: RGWSpec
+  :noindex:
 
 .. py:currentmodule:: orchestrator
 

diff --git a/src/python-common/ceph/deployment/service_spec.py b/src/python-common/ceph/deployment/service_spec.py
index e8c47b4e47b7fcc6fa23fd63c9ed7587ac2e4fc0..eb4e6c2e9210eb228439e281aab539278cc65f01 100644 (file)
--- a/src/python-common/ceph/deployment/service_spec.py
+++ b/src/python-common/ceph/deployment/service_spec.py
@@ -411,7 +411,6 @@ class ServiceSpec(object):
 
     This structure is supposed to be enough information to
     start the services.
-
     """
     KNOWN_SERVICE_TYPES = 'alertmanager crash grafana iscsi mds mgr mon nfs ' \
                           'node-exporter osd prometheus rbd-mirror rgw ' \
@@ -466,15 +465,37 @@ class ServiceSpec(object):
                  preview_only: bool = False,
                  networks: Optional[List[str]] = None,
                  ):
+
+        #: See :ref:`orchestrator-cli-placement-spec`.
         self.placement = PlacementSpec() if placement is None else placement  # type: PlacementSpec
 
         assert service_type in ServiceSpec.KNOWN_SERVICE_TYPES, service_type
+        #: The type of the service. Needs to be either a Ceph
+        #: service (``mon``, ``crash``, ``mds``, ``mgr``, ``osd`` or
+        #: ``rbd-mirror``), a gateway (``nfs`` or ``rgw``), part of the
+        #: monitoring stack (``alertmanager``, ``grafana``, ``node-exporter`` or
+        #: ``prometheus``) or (``container``) for custom containers.
         self.service_type = service_type
+
+        #: The name of the service. Required for ``iscsi``, ``mds``, ``nfs``, ``osd``, ``rgw``,
+        #: ``container``, ``ingress``
         self.service_id = None
+
         if self.service_type in self.REQUIRES_SERVICE_ID:
             self.service_id = service_id
+
+        #: If set to ``true``, the orchestrator will not deploy nor remove
+        #: any daemon associated with this service. Placement and all other properties
+        #: will be ignored. This is useful, if you do not want this service to be
+        #: managed temporarily. For cephadm, See :ref:`cephadm-spec-unmanaged`
         self.unmanaged = unmanaged
         self.preview_only = preview_only
+
+        #: A list of network identities instructing the daemons to only bind
+        #: on the particular networks in that list. In case the cluster is distributed
+        #: across multiple networks, you can add multiple networks. See
+        #: :ref:`cephadm-monitoring-networks-ports`,
+        #: :ref:`cephadm-rgw-networks` and :ref:`cephadm-mgr-networks`.
         self.networks: List[str] = networks or []
 
         self.config: Optional[Dict[str, str]] = None
@@ -519,6 +540,8 @@ class ServiceSpec(object):
         the next two major releases (octoups, pacific).
 
         :param json_spec: A valid dict with ServiceSpec
+
+        :meta private:
         """
 
         if not isinstance(json_spec, dict):
@@ -698,7 +721,21 @@ class RGWSpec(ServiceSpec):
     """
     Settings to configure a (multisite) Ceph RGW
 
+    .. code-block:: yaml
+
+        service_type: rgw
+        service_id: myrealm.myzone
+        spec:
+            rgw_realm: myrealm
+            rgw_zone: myzone
+            ssl: true
+            rgw_frontend_port: 1234
+            rgw_frontend_type: beast
+            rgw_frontend_ssl_certificate: ...
+
+    See also: :ref:`orchestrator-cli-service-spec`
     """
+
     MANAGED_CONFIG_OPTIONS = ServiceSpec.MANAGED_CONFIG_OPTIONS + [
         'rgw_zone',
         'rgw_realm',
@@ -732,11 +769,17 @@ class RGWSpec(ServiceSpec):
             placement=placement, unmanaged=unmanaged,
             preview_only=preview_only, config=config, networks=networks)
 
-        self.rgw_realm = rgw_realm
-        self.rgw_zone = rgw_zone
-        self.rgw_frontend_port = rgw_frontend_port
-        self.rgw_frontend_ssl_certificate = rgw_frontend_ssl_certificate
-        self.rgw_frontend_type = rgw_frontend_type
+        #: The RGW realm associated with this service. Needs to be manually created
+        self.rgw_realm: Optional[str] = rgw_realm
+        #: The RGW zone associated with this service. Needs to be manually created
+        self.rgw_zone: Optional[str] = rgw_zone
+        #: Port of the RGW daemons
+        self.rgw_frontend_port: Optional[int] = rgw_frontend_port
+        #: List of SSL certificates
+        self.rgw_frontend_ssl_certificate: Optional[List[str]] = rgw_frontend_ssl_certificate
+        #: civetweb or beast (default: beast). See :ref:`rgw_frontends`
+        self.rgw_frontend_type: Optional[str] = rgw_frontend_type
+        #: enable SSL
         self.ssl = ssl
 
     def get_port_start(self) -> List[int]: