Documentation updates regarding ActivityPub and other things

README.md

@@ -6,11 +6,11 @@
 
 # federation
 
-Python library to abstract social web federation protocols like Diaspora.
+Python library to abstract social web federation protocols like Diaspora and ActivityPub.
 
 ## Introduction
 
-The aim of `federation` is to provide and abstract multiple social web protocols like Diaspora 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.
+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.
 
@@ -18,7 +18,7 @@ While the library does aim to provide an easy way to implement protocols like Di
 
 ## Status
 
-Currently the library supports a part of the Diaspora protocol with remaining parts being constantly added. See the [Diaspora](http://federation.readthedocs.io/en/latest/protocols.html#diaspora) protocol page for support 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.
 
 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.
 
@@ -42,4 +42,4 @@ See [development and support documentation](http://federation.readthedocs.io/en/
 
 ### Author
 
-Jason Robinson / https://jasonrobinson.me / https://github.com/jaywink / https://git.feneas.org/jaywink
+Jason Robinson / https://jasonrobinson.me / https://git.feneas.org/jaywink / https://github.com/jaywink 

docs/development.rst

@@ -34,8 +34,6 @@ Built documentation is available at ``docs/_build/html/index.html``.
 Contact for help
 ----------------
 
-Easiest via FreeNode IRC, channel ``#python-federation`` (`webchat here <http://webchat.freenode.net?channels=%23python-federation&uio=d4>`_).
-
-There is also a `Gitter chat <https://gitter.im/python-federation/Lobby>`_ available.
+Easiest via Matrix on channel ``#socialhome:matrix.org``.
 
 You can also ask questions or give feedback via issues.

docs/example_projects.rst

@@ -5,5 +5,6 @@ Projects using federation
 
 For examples on how to integrate this library into your project, check these examples:
 
-* `Socialhome <https://github.com/jaywink/socialhome>`_ - a federated home page builder slash personal social network server with high emphasis on card style content visualization.
-* `Social-Relay <https://github.com/jaywink/social-relay>`_ - a reference server for the public content relay system that uses the Diaspora protocol.
+* `Socialhome <https://socialhome.network>`_ - a federated home page builder slash personal social network server with high emphasis on card style content visualization.
+* `Social-Relay <https://git.feneas.org/jaywink/social-relay>`_ - a reference server for the public content relay system that uses the Diaspora protocol.
+* `The Federation info <https://the-federation.info>`_ - statistics and node list for the federated web.

docs/introduction.rst

@@ -1,7 +1,7 @@
 Introduction
 ============
 
-The aim of *federation* is to provide and abstract multiple social web protocols like Diaspora 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.
+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.
 
@@ -10,7 +10,7 @@ While the library does aim to provide an easy way to implement protocols like Di
 Status
 ------
 
-Currently the library supports a part of the Diaspora protocol with remaining parts being constantly added. See the `Diaspora <http://federation.readthedocs.io/en/latest/protocols.html#diaspora>`_ protocol page for support 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.
 
 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.
 
@@ -40,5 +40,5 @@ License
 Author
 ......
 
-Jason Robinson / `jasonrobinson.me <https://jasonrobinson.me>`_ / `GitHub <https://github.com/jaywink>`_ / `GitLab <https://git.feneas.org/jaywink>`_
+Jason Robinson / `jasonrobinson.me <https://jasonrobinson.me>`_ / `GitLab <https://git.feneas.org/jaywink>`_ / `GitHub <https://github.com/jaywink>`_
 

docs/protocols.rst

@@ -1,22 +1,25 @@
 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.
+
+For example implementations in real life projects check :ref:`example-projects`.
+
 .. _diaspora:
 
 Diaspora
 --------
 
-Currently the library supports a part of the protocol with remaining parts being constantly added.
+This library only supports the `current renewed version <http://diaspora.github.io/diaspora_federation/>`_ of the protocol. Compatibility for the legacy version was dropped in version 0.18.0.
 
-Note! Diaspora project is currently rewriting parts of the protocol. This library aims to support the `new version <http://diaspora.github.io/diaspora_federation/>`_. When possible, compatibility will be kept with the current and legacy versions but this is not the main objective.
+The feature set supported is the following:
 
-The feature set supported by this release is approximately the following:
-
-* WebFinger, hCard and other discovery documents
+* Webfinger, hCard and other discovery documents
 * NodeInfo 1.0 documents
 * Social-Relay documents
 * Magic envelopes, signatures and other transport method related necessities
 * Entities as follows:
+
    * Comment
    * Like
    * Photo
@@ -26,6 +29,15 @@ The feature set supported by this release is approximately the following:
    * Contact
    * Reshare
 
-Implementation unfortunately currently requires knowledge of how Diaspora discovery works as the implementer has to implement all the necessary views correctly (even though this library provides document generators). However, the magic envelope, signature and entity building is all abstracted inside the library.
+.. _activitypub:
 
-For example implementations in real life projects check :ref:`example-projects`.
+ActivityPub
+-----------
+
+Features currently supported:
+
+* Webfinger
+* Entities as follows:
+
+   * Profile
+   * Post

docs/usage.rst

@@ -98,6 +98,7 @@ 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.
 
+.. autofunction:: federation.entities.activitypub.django.views.activitypub_object_view
 .. autofunction:: federation.hostmeta.django.generators.rfc7033_webfinger_view
 .. autofunction:: federation.hostmeta.django.generators.nodeinfo2_view
 
@@ -116,13 +117,15 @@ Some settings need to be set in Django settings. An example is below:
 
     FEDERATION = {
         "base_url": "https://myserver.domain.tld,
+        "get_object_function": "myproject.utils.get_object",
         "get_profile_function": "myproject.utils.get_profile",
         "nodeinfo2_function": "myproject.utils.get_nodeinfo2_data",
         "search_path": "/search/?q=",
     }
 
 * ``base_url`` is the base URL of the server, ie protocol://domain.tld.
-* ``get_profile_function`` should be the full path to a function that will return a dictionary with profile information. The function should take the following parameters: ``handle``, ``guid`` and ``request``. It should look up a profile with one or more of the provided parameters. It should return a ``Profile`` entity.
+* ``get_object_function`` should be the full path to a function that will return the object matching the ActivityPub ID that is passed to this function. Needed for the ``activitypub_object_view`` decorator.
+* ``get_profile_function`` should be the full path to a function that should return a ``Profile`` entity. The function should take the following parameters: ``handle``, ``guid`` and ``request``. It should look up a profile with one or more of the provided parameters.
 * ``nodeinfo2_function`` (optional) function that returns data for generating a `NodeInfo2 document <https://github.com/jaywink/nodeinfo2>`_. Once configured the path ``/.well-known/x-nodeinfo2`` will automatically generate a NodeInfo2 document. The function should return a ``dict`` corresponding to the NodeInfo2 schema, with the following minimum items:
 
 ::
@@ -140,7 +143,7 @@ Some settings need to be set in Django settings. An example is below:
 Protocols
 ---------
 
-The code for opening and creating protocol messages lives under each protocol module in ``federation.protocols``. Currently Diaspora protocol is the only protocol supported.
+The code for opening and creating protocol messages lives under each protocol module in ``federation.protocols``.
 
 Each protocol defines a ``protocol.Protocol`` class under it's own module. This is expected to contain certain methods that are used by the higher level functions that are called on incoming messages and when sending outbound messages. Everything that is needed to transform an entity into a message payload and vice versa should be here.