put formatters/transmitters info into publish doc

superdesk · Oct 4, 2016 · 917ca92 · 917ca92
1 parent a8ca0f3
commit 917ca92
Show file tree

Hide file tree

Showing 25 changed files with 150 additions and 192 deletions.
diff --git a/apps/publish/formatters/__init__.py b/apps/publish/formatters/__init__.py
@@ -8,7 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-import apps.publish.formatters.newsml_g2_formatter  # NOQA
 from superdesk import get_backend
 from apps.publish.formatters.service import FormattersService
 from apps.publish.formatters.resource import FormattersResource

diff --git a/docs/formatters/email.rst b/docs/formatters/email.rst
diff --git a/docs/formatters/newsml.rst b/docs/formatters/newsml.rst
diff --git a/docs/formatters/newsmlg2.rst b/docs/formatters/newsmlg2.rst
diff --git a/docs/formatters/ninjs.rst b/docs/formatters/ninjs.rst
diff --git a/docs/formatters/nitf.rst b/docs/formatters/nitf.rst
diff --git a/docs/publish.rst b/docs/publish.rst
@@ -78,17 +78,22 @@ Enqueueing is done via:
 
 There it finds all subscribers that should recieve the item and if any it will format the item and queue transmission.
 
-Supported output formats are:
+Output Formats
+--------------
 
-.. toctree::
-    :maxdepth: 1
+.. module:: superdesk.publish.formatters
 
-    formatters/ninjs
-    formatters/nitf
-    formatters/newsml
-    formatters/newsmlg2
-    formatters/email
+.. autoclass:: NINJSFormatter
 
+Superdesk NINJS Schema in :download:`JSON <superdesk-ninjs-schema.json>`.
+
+.. autoclass:: NITFFormatter
+
+.. autoclass:: NewsML12Formatter
+
+.. autoclass:: NewsMLG2Formatter
+
+.. autoclass:: EmailFormatter
 
 Transmission
 ------------
@@ -99,13 +104,17 @@ Last task is to send items to subscribers, that's handled via another async task
 
 This task runs every 10s.
 
-There are different means of transport:
+Content Transmitters
+--------------------
+
+.. module:: superdesk.publish.transmitters
+
+.. autoclass:: HTTPPushService
+
+.. autoclass:: FTPPublishService
+
+.. autoclass:: FilePublishService
 
-.. toctree::
-    :maxdepth: 1
+.. autoclass:: EmailPublishService
 
-    transmitters/http-push
-    transmitters/ftp
-    transmitters/file
-    transmitters/email
-    transmitters/odbc
+.. autoclass:: ODBCPublishService
diff --git a/docs/transmitters/email.rst b/docs/transmitters/email.rst
diff --git a/docs/transmitters/file.rst b/docs/transmitters/file.rst
diff --git a/docs/transmitters/ftp.rst b/docs/transmitters/ftp.rst
diff --git a/docs/transmitters/http-push.rst b/docs/transmitters/http-push.rst
diff --git a/docs/transmitters/odbc.rst b/docs/transmitters/odbc.rst
diff --git a/superdesk/publish/formatters/__init__.py b/superdesk/publish/formatters/__init__.py
@@ -128,7 +128,8 @@ def get_all_formatters():
     return formatters
 
 
-import superdesk.publish.formatters.nitf_formatter  # NOQA
-import superdesk.publish.formatters.ninjs_formatter  # NOQA
-import superdesk.publish.formatters.newsml_1_2_formatter  # NOQA
-import superdesk.publish.formatters.email_formatter  # NOQA
+from .nitf_formatter import NITFFormatter  # NOQA
+from .ninjs_formatter import NINJSFormatter  # NOQA
+from .newsml_1_2_formatter import NewsML12Formatter  # NOQA
+from .newsml_g2_formatter import NewsMLG2Formatter  # NOQA
+from .email_formatter import EmailFormatter  # NOQA
diff --git a/superdesk/publish/formatters/email_formatter.py b/superdesk/publish/formatters/email_formatter.py
@@ -8,27 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-"""Superdesk Email formatter.
-
-- Does not support any media output, it's for text items only.
-
-It uses templates to render items, those can be overriden to customize the output:
-
-- ``email_article_subject.txt``
-    email subject
-
-- ``email_article_body.txt``
-    email text content
-
-- ``email_article_body.html``
-    email html content
-
-It gets ``article`` with item data, can be used in templates like::
-
-   <strong>{{ article.headline }}</strong>
-
-"""
-
 from superdesk.publish.formatters import Formatter
 from superdesk.metadata.item import ITEM_TYPE, CONTENT_TYPE, FORMAT, FORMATS
 from flask import render_template
@@ -40,6 +19,27 @@
 
 
 class EmailFormatter(Formatter):
+    """Superdesk Email formatter.
+
+    - Does not support any media output, it's for text items only.
+
+    It uses templates to render items, those can be overriden to customize the output:
+
+    - ``email_article_subject.txt``
+        email subject
+
+    - ``email_article_body.txt``
+        email text content
+
+    - ``email_article_body.html``
+        email html content
+
+    It gets ``article`` with item data, can be used in templates like::
+
+       <strong>{{ article.headline }}</strong>
+
+    """
+
     def format(self, article, subscriber, codes=None):
         formatted_article = deepcopy(article)
         pub_seq_num = superdesk.get_resource_service('subscribers').generate_sequence_number(subscriber)

diff --git a/superdesk/publish/formatters/newsml_1_2_formatter.py b/superdesk/publish/formatters/newsml_1_2_formatter.py
@@ -8,10 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-"""NewsML 1.2 Superdesk Formatter
-
-"""
-
 import time
 import logging
 import xml.etree.ElementTree as etree

diff --git a/...publish/formatters/newsml_g2_formatter.py → ...publish/formatters/newsml_g2_formatter.py b/...publish/formatters/newsml_g2_formatter.py → ...publish/formatters/newsml_g2_formatter.py
@@ -10,20 +10,21 @@
 
 """NewsML G2 Superdesk formatter"""
 
+import superdesk
 import xml.etree.ElementTree as etree
-from xml.etree.ElementTree import SubElement
 
+from bs4 import BeautifulSoup
+from xml.etree.ElementTree import SubElement
 from flask import current_app as app
+
 from superdesk.publish.formatters import Formatter
 from superdesk.metadata.item import ITEM_TYPE, CONTENT_TYPE, EMBARGO, FORMATS, FORMAT
 from superdesk.utc import utcnow
-import superdesk
 from superdesk.errors import FormatterError
 from superdesk.publish.formatters.nitf_formatter import NITFFormatter
-from apps.archive.common import ARCHIVE, get_utc_schedule
 from superdesk.metadata.packages import PACKAGE_TYPE, REFS, RESIDREF, ROLE, GROUPS, GROUP_ID, ID_REF
-from bs4 import BeautifulSoup
 from superdesk.filemeta import get_filemeta
+from apps.archive.common import ARCHIVE, get_utc_schedule
 
 
 def get_newsml_provider_id():

diff --git a/...sh/formatters/newsml_g2_formatter_test.py → ...sh/formatters/newsml_g2_formatter_test.py b/...sh/formatters/newsml_g2_formatter_test.py → ...sh/formatters/newsml_g2_formatter_test.py
diff --git a/superdesk/publish/formatters/ninjs_formatter.py b/superdesk/publish/formatters/ninjs_formatter.py
@@ -45,7 +45,21 @@ def format_cv_item(item):
 
 class NINJSFormatter(Formatter):
     """
-    NINJS Formatter
+    The schema we use for the ninjs format is an extension
+    of `the standard ninjs schema <http://www.iptc.org/std/ninjs/ninjs-schema_1.1.json>`_.
+
+    *Changes from ninjs schema*:
+
+    * ``uri`` was replaced by ``guid``: ``uri`` should be the resource identifier on the web
+        but since the item was not published yet it can't be determined at this point
+    * added ``priority`` field
+    * added ``service`` field
+    * added ``slugline`` field
+    * added ``keywords`` field
+
+    Associations dictionary may contain entire items like
+    in `ninjs example <http://dev.iptc.org/ninjs-Examples-3>`_ or just the item ``guid``
+    and ``type``. In the latest case the items are sent separately before the package item.
     """
 
     direct_copy_properties = ('versioncreated', 'usageterms', 'language', 'headline', 'copyrightnotice',

diff --git a/superdesk/publish/formatters/nitf_formatter.py b/superdesk/publish/formatters/nitf_formatter.py
@@ -8,11 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-"""NITF Formatter for Superdesk
-
-Format items to `NITF <https://iptc.org/standards/nitf/>`_ version *3.6*.
-"""
-
 import xml.etree.ElementTree as etree
 from xml.etree.ElementTree import SubElement
 from flask import current_app as app
@@ -25,8 +20,9 @@
 
 
 class NITFFormatter(Formatter):
-    """
-    NITF Formatter
+    """NITF Formatter for Superdesk
+
+    Format items to `NITF <https://iptc.org/standards/nitf/>`_ version *3.6*.
     """
 
     XML_ROOT = '<?xml version="1.0"?>'

diff --git a/superdesk/publish/transmitters/__init__.py b/superdesk/publish/transmitters/__init__.py
@@ -8,8 +8,8 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-import superdesk.publish.transmitters.ftp  # NOQA
-import superdesk.publish.transmitters.email  # NOQA
-import superdesk.publish.transmitters.odbc  # NOQA
-import superdesk.publish.transmitters.file_output  # NOQA
-import superdesk.publish.transmitters.http_push  # NOQA
+from .ftp import FTPPublishService  # NOQA
+from .email import EmailPublishService  # NOQA
+from .odbc import ODBCPublishService  # NOQA
+from .file_output import FilePublishService  # NOQA
+from .http_push import HTTPPushService  # NOQA
diff --git a/superdesk/publish/transmitters/email.py b/superdesk/publish/transmitters/email.py
@@ -8,11 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-"""Superdesk Email transmitter.
-
-Works only with :doc:`../formatters/email` formatter.
-"""
-
 from superdesk.emails import send_email
 from flask import current_app as app
 from superdesk.publish import register_transmitter
@@ -23,7 +18,12 @@
 
 
 class EmailPublishService(PublishService):
-    """Email Publish Service."""
+    """Email Transmitter
+
+    Works only with email formatter.
+
+    :param recipients: email addresses separated by ``;``
+    """
 
     def _transmit(self, queue_item, subscriber):
         config = queue_item.get('destination', {}).get('config', {})

diff --git a/superdesk/publish/transmitters/file_output.py b/superdesk/publish/transmitters/file_output.py
@@ -8,11 +8,6 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
-"""Superdesk file transmitter.
-
-It creates files on superdesk server in configured folder.
-"""
-
 from superdesk.publish.publish_service import PublishService
 from superdesk.publish import register_transmitter
 from superdesk.errors import PublishFileError
@@ -22,6 +17,11 @@
 
 
 class FilePublishService(PublishService):
+    """Superdesk file transmitter.
+
+    It creates files on superdesk server in configured folder.
+    """
+
     def _transmit(self, queue_item, subscriber):
         try:
             config = queue_item['destination']['config']