Some clarifications for the docs and readme

CHANGELOG.md

@@ -4,8 +4,6 @@
 
 ### Added
 
-* Work has started on ActivityPub support 🎉
-
 * Base entities `Post`, `Comment` and `Image` now accept an `url` parameter. This will be used when serializing the entities to AS2 for ActivityPub.
 
 * RFC7033 webfinger generator now has compatibility to platforms using it with ActivityPub. It now lists `aliases` pointing to the ActivityPub entity ID and profile URL. Also there is a `rel=self` to point to the `application/activity+json` AS2 document location.

README.md

@@ -4,21 +4,26 @@
 
 # federation
 
-Python library to abstract social web federation protocols like Diaspora and ActivityPub.
+Python library to abstract social web federation protocols like ActivityPub and Diaspora.
 
 ## Introduction
 
-The aim of `federation` is to provide and abstract multiple social web protocols like Diaspora and ActivityPub in one package. This way applications can be built to (almost) transparently support many protocols without the app builder having to know everything about those protocols.
-
-While the library does aim to provide an easy way to implement protocols like Diaspora into your application, it will not be a one to one mirror image of said protocols. The idea is to present one unified collection of entities and high level methods to the application to use. Since protocols can support different feature sets or have different ideas on even simple entities like status messages, it would be impossible to model the core entities according to a single protocol.
+The aim of `federation` is to provide and abstract multiple social web protocols like 
+ActivityPub and Diaspora in one package, over an easy to use and understand Python API. 
+This way applications can be built to (almost) transparently support many protocols 
+without the app builder having to know everything about those protocols.
 
 ![](http://federation.readthedocs.io/en/latest/_images/generic_diagram.png)
 
 ## Status
 
-Currently two protocols are being focused on. Diaspora is considered in relatively stable status with most of the protocol implemented. ActivityPub support is work in progress.
+Currently two protocols are being focused on. Diaspora is considered to be stable with most 
+of the protocol implemented. ActivityPub support should be considered as alpha - all the basic
+things work but there are likely to be a lot of compatibility issues with other ActivityPub
+implementations.
 
-The code base is well tested and in use in several projects. Backward incompatible changes will however be made at this stage still, however those will be clearly documented in changelog entries.
+The code base is well tested and in use in several projects. Backward incompatible changes 
+will be clearly documented in changelog entries.
 
 ## Additional information
 

docs/development.rst

@@ -34,6 +34,7 @@ Built documentation is available at ``docs/_build/html/index.html``.
 Contact for help
 ----------------
 
-Easiest via Matrix on channel ``#socialhome:matrix.org``.
+Easiest via Matrix on room ``#socialhome:feneas.org``. There is a bridged
+Freenode channel as well found at ``#socialhome``.
 
 You can also ask questions or give feedback via issues.

docs/index.rst

@@ -6,7 +6,7 @@
 federation
 ==========
 
-Python library to abstract social web federation protocols like Diaspora.
+Python library to abstract social web federation protocols like ActivityPub and Diaspora.
 
 Contents:
 

docs/introduction.rst

@@ -1,18 +1,23 @@
 Introduction
 ============
 
-The aim of *federation* is to provide and abstract multiple social web protocols like Diaspora and ActivityPub in one package. This way applications can be built to (almost) transparently support many protocols without the app builder having to know everything about those protocols.
-
-While the library does aim to provide an easy way to implement protocols like Diaspora into your application, it will not be a one to one mirror image of said protocols. The idea is to present one unified collection of entities and high level methods to the application to use. Since protocols can support different feature sets or have different ideas on even simple entities like status messages, it would be impossible to model the core entities according to a single protocol.
+The aim of ``federation`` is to provide and abstract multiple social web protocols like
+ActivityPub and Diaspora in one package, over an easy to use and understand Python API.
+This way applications can be built to (almost) transparently support many protocols
+without the app builder having to know everything about those protocols.
 
 .. image:: _static/generic_diagram.png
 
 Status
 ------
 
-Currently two protocols are being focused on. Diaspora is considered in relatively stable status with most of the protocol implemented. ActivityPub support is work in progress.
+Currently two protocols are being focused on. Diaspora is considered to be stable with most
+of the protocol implemented. ActivityPub support should be considered as alpha - all the basic
+things work but there are likely to be a lot of compatibility issues with other ActivityPub
+implementations.
 
-The code base is well tested and in use in several projects. Backward incompatible changes will however be made at this stage still, however those will be clearly documented in changelog entries.
+The code base is well tested and in use in several projects. Backward incompatible changes
+will be clearly documented in changelog entries.
 
 Additional information
 ----------------------

docs/protocols.rst

@@ -1,7 +1,10 @@
 Protocols
 =========
 
-Currently two protocols are being focused on. Diaspora is considered in relatively stable status with most of the protocol implemented. ActivityPub support is work in progress.
+Currently two protocols are being focused on. Diaspora is considered to be stable with most
+of the protocol implemented. ActivityPub support should be considered as alpha - all the basic
+things work but there are likely to be a lot of compatibility issues with other ActivityPub
+implementations.
 
 For example implementations in real life projects check :ref:`example-projects`.
 
@@ -39,7 +42,7 @@ Features currently supported:
 * Webfinger
 * Objects and activities as follows:
 
-   * Actor (Person)
+   * Actor (Person outbound, Person, Organization, Service inbound)
    * Note, Article and Page (Create, Delete, Update)
      * These become a ``Post`` or ``Comment`` depending on ``inReplyTo``.
    * Attachment images from the above objects
@@ -65,11 +68,20 @@ The following keys will be set on the entity based on the ``source`` property ex
   * ``_rendered_content`` will be the object ``content``
   * ``raw_content`` will object ``content`` run through a HTML2Markdown renderer
 
-For outbound entities, ``raw_content`` is expected to be in ``text/markdown``, specifically CommonMark. When sending payloads, ``raw_content`` will be rendered via the ``commonmark`` library into ``object.content``. The original ``raw_content`` will be added to the ``object.source`` property.
+For outbound entities, ``raw_content`` is expected to be in ``text/markdown``,
+specifically CommonMark. When sending payloads, ``raw_content`` will be rendered via
+the ``commonmark`` library into ``object.content``. The original ``raw_content``
+will be added to the ``object.source`` property.
 
 Images
 ......
 
-Any images referenced in the ``raw_content`` of outbound entities will be extracted into ``object.attachment`` objects, for receivers that don't support inline images. These attachments will have a ``pyfed:inlineImage`` property set to ``true`` to indicate the image has been extrated from the content. Receivers should ignore the inline image attachments if they support showing ``<img>`` HTML tags or the markdown content in ``object.source``.
+Any images referenced in the ``raw_content`` of outbound entities will be extracted
+into ``object.attachment`` objects, for receivers that don't support inline images.
+These attachments will have a ``pyfed:inlineImage`` property set to ``true`` to
+indicate the image has been extrated from the content. Receivers should ignore the
+inline image attachments if they support showing ``<img>`` HTML tags or the markdown
+content in ``object.source``.
 
-For inbound entities we do this automatically by not including received attachments in the entity ``_children`` attribute.
+For inbound entities we do this automatically by not including received attachments in
+the entity ``_children`` attribute.

docs/usage.rst

@@ -5,7 +5,10 @@ Usage
 Entities
 --------
 
-Federation has it's own base entity classes. When incoming messages are processed, the protocol specific entity mappers transform the messages into our base entities. In reverse, when creating outgoing payloads, outgoing protocol specific messages are constructed from the base entities.
+Federation has it's own base entity classes. When incoming messages are processed, the
+protocol specific entity mappers transform the messages into our base entities. In
+reverse, when creating outgoing payloads, outgoing protocol specific messages are
+constructed from the base entities.
 
 Entity types are as follows below.
 
@@ -22,21 +25,29 @@ Entity types are as follows below.
 Protocol entities
 .................
 
-Each protocol additionally has it's own variants of the base entities, for example Diaspora entities in ``federation.entities.diaspora.entities``. All the protocol specific entities subclass the base entities so you can safely work with for example ``DiasporaPost`` and use ``isinstance(obj, Post)``.
+Each protocol additionally has it's own variants of the base entities, for example
+Diaspora entities in ``federation.entities.diaspora.entities``. All the protocol
+specific entities subclass the base entities so you can safely work with for example
+``DiasporaPost`` and use ``isinstance(obj, Post)``.
 
-When creating incoming objects from messages, protocol specific entity classes are returned. This is to ensure protocol specific extra attributes or methods are passed back to the caller.
+When creating incoming objects from messages, protocol specific entity classes are
+returned. This is to ensure protocol specific extra attributes or methods are
+passed back to the caller.
 
-For sending messages out, either base or protocol specific entities can be passed to the outbound senders. Base entities should be preferred unless the caller knows which protocol to send to.
+For sending messages out, either base or protocol specific entities can be passed
+to the outbound senders.
 
-If you need the correct protocol speficic entity class from the base entity, each protocol will define a ``get_outbound_entity`` function, for example the Diaspora function as follows.
+If you need the correct protocol speficic entity class from the base entity,
+each protocol will define a ``get_outbound_entity`` function.
 
+.. autofunction:: federation.entities.activitypub.mappers.get_outbound_entity
 .. autofunction:: federation.entities.diaspora.mappers.get_outbound_entity
 
 Federation identifiers
 ......................
 
-All entities have an ``id`` to guarantee them a unique name in the network. The format of the ``id`` depends on the
-protocol in question.
+All entities have an ``id`` to guarantee them a unique name in the network.
+The format of the ``id`` depends on the protocol in question.
 
 * ActivityPub: maps to the object ``id`` (whether wrapped in an Activity or not)
 * Diaspora: maps to ``guid`` for the entity.
@@ -109,9 +120,13 @@ before sending.
 Discovery
 ---------
 
-Federation provides many generators to allow providing the discovery documents that are necessary for the Diaspora protocol for example. The have been made as Pythonic as possible so that library users don't have to meddle with the various documents and their internals.
+Federation provides many generators to allow providing discovery documents.
+They have been made as Pythonic as possible so that library users don't have to
+meddle with the various documents and their internals.
 
-The protocols themselves are too complex to document within this library, please consult protocol documentation on what kind of discovery documents are expected to be served by the application.
+The protocols themselves are too complex to document within this library,
+please consult protocol documentation on what kind of discovery documents are expected to
+be served by the application.
 
 Generators
 ..........
@@ -150,7 +165,8 @@ High level utility functions to fetch remote objects. These should be favoured i
 Inbound
 -------
 
-High level utility functions to pass incoming messages to. These should be favoured instead of protocol specific utility functions.
+High level utility functions to pass incoming messages to. These should be favoured
+instead of protocol specific utility functions.
 
 
 .. autofunction:: federation.inbound.handle_receive
@@ -161,7 +177,6 @@ Outbound
 
 High level utility functions to pass outbound entities to. These should be favoured instead of protocol specific utility functions.
 
-.. autofunction:: federation.outbound.handle_create_payload
 .. autofunction:: federation.outbound.handle_send
 
 Django
@@ -169,7 +184,8 @@ Django
 
 Some ready provided views and URL configuration exist for Django.
 
-Note! Django is not part of the normal requirements for this library. It must be installed separately.
+Note! Django is not part of the normal requirements for this library.
+It must be installed separately.
 
 .. autofunction:: federation.entities.activitypub.django.views.activitypub_object_view
 .. autofunction:: federation.hostmeta.django.generators.rfc7033_webfinger_view
@@ -234,6 +250,13 @@ Utils
 
 Various utils are provided for internal and external usage.
 
+ActivityPub
+...........
+
+.. autofunction:: federation.utils.activitypub.retrieve_and_parse_content
+.. autofunction:: federation.utils.activitypub.retrieve_and_parse_document
+.. autofunction:: federation.utils.activitypub.retrieve_and_parse_profile
+
 Diaspora
 ........
 
@@ -259,6 +282,10 @@ Network
 .. autofunction:: federation.utils.network.fetch_host_ip_and_country
 .. autofunction:: federation.utils.network.send_document
 
+Protocols
+.........
+
+.. autofunction:: federation.utils.protocols.identify_recipient_protocol
 
 Exceptions
 ----------