mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-09-19 04:59:01 +00:00
doc/dev: Update developer documentation with new import path
Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org> Reviewed-by: James Valleroy <jvalleroy@mailbox.org>
This commit is contained in:
Sunil Mohan Adapa
James Valleroy
parent
5e17a84c8a
commit
d128836d2f
@ -20,7 +20,7 @@ from datetime import datetime
|
||||
import django
|
||||
|
||||
sys.path.insert(0, os.path.abspath('../../'))
|
||||
os.environ['DJANGO_SETTINGS_MODULE'] = 'plinth.settings'
|
||||
os.environ['DJANGO_SETTINGS_MODULE'] = 'freedombox.settings'
|
||||
django.setup()
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
@ -6,5 +6,5 @@ Action Utils
|
||||
Several utilities to help with the implementation of actions and diagnostic
|
||||
tests are implemented in this module.
|
||||
|
||||
.. automodule:: plinth.action_utils
|
||||
.. automodule:: freedombox.action_utils
|
||||
:members:
|
||||
|
||||
@ -1,16 +1,14 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
Actions
|
||||
^^^^^^^
|
||||
Privileged Actions
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
FreedomBox's web front does not directly change any aspect of the underlying
|
||||
operating system. Instead, it calls upon **actions**, as shell commands. Actions
|
||||
live in ``/usr/share/plinth/actions`` directory. They require no interaction
|
||||
beyond passing command line arguments or taking sensitive arguments via stdin.
|
||||
They change the operation of the services and apps of the FreedomBox and nothing
|
||||
else. These actions are also directly usable by a skilled administrator.
|
||||
FreedomBox Service performs most changes to the underlying operating system
|
||||
using remote calls into the **freedombox-privileged** daemon or other daemons
|
||||
such as NetworkManager and UDisks.
|
||||
|
||||
The following documentation for the ``actions`` module.
|
||||
The following documentation for the ``actions`` module which contains function
|
||||
decorators to mark a method to run with privileged permissions.
|
||||
|
||||
.. automodule:: plinth.actions
|
||||
.. automodule:: freedombox.actions
|
||||
:members: privileged
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
App
|
||||
---
|
||||
|
||||
.. autoclass:: plinth.app.App
|
||||
.. autoclass:: freedombox.app.App
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Backups
|
||||
^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.backups.components.BackupRestore
|
||||
.. autoclass:: freedombox.modules.backups.components.BackupRestore
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Configuration
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.config.DropinConfigs
|
||||
.. autoclass:: freedombox.config.DropinConfigs
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Container
|
||||
^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.container.Container
|
||||
.. autoclass:: freedombox.container.Container
|
||||
:members:
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Coturn
|
||||
^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.coturn.components.TurnConsumer
|
||||
.. autoclass:: freedombox.modules.coturn.components.TurnConsumer
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.modules.coturn.components.TurnConfiguration
|
||||
.. autoclass:: freedombox.modules.coturn.components.TurnConfiguration
|
||||
:members:
|
||||
|
||||
@ -3,11 +3,11 @@
|
||||
Daemon
|
||||
^^^^^^
|
||||
|
||||
.. autoclass:: plinth.daemon.Daemon
|
||||
.. autoclass:: freedombox.daemon.Daemon
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.daemon.RelatedDaemon
|
||||
.. autoclass:: freedombox.daemon.RelatedDaemon
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.daemon.SharedDaemon
|
||||
.. autoclass:: freedombox.daemon.SharedDaemon
|
||||
:members:
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Domain Name
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.names.components.DomainName
|
||||
.. autoclass:: freedombox.modules.names.components.DomainName
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.modules.names.components.DomainType
|
||||
.. autoclass:: freedombox.modules.names.components.DomainType
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
EnableState
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.app.EnableState
|
||||
.. autoclass:: freedombox.app.EnableState
|
||||
:members:
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Firewall
|
||||
^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.firewall.components.Firewall
|
||||
.. autoclass:: freedombox.modules.firewall.components.Firewall
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.modules.firewall.components.FirewallLocalProtection
|
||||
.. autoclass:: freedombox.modules.firewall.components.FirewallLocalProtection
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Frontpage
|
||||
^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.frontpage.Shortcut
|
||||
.. autoclass:: freedombox.frontpage.Shortcut
|
||||
:members:
|
||||
|
||||
@ -27,20 +27,20 @@ Components
|
||||
Base Classes
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.app.Component
|
||||
.. autoclass:: freedombox.app.Component
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.app.LeaderComponent
|
||||
.. autoclass:: freedombox.app.LeaderComponent
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.app.FollowerComponent
|
||||
.. autoclass:: freedombox.app.FollowerComponent
|
||||
:members:
|
||||
|
||||
Other Classes
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.diagnostic_check.DiagnosticCheck
|
||||
.. autoclass:: freedombox.diagnostic_check.DiagnosticCheck
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.diagnostic_check.Result
|
||||
.. autoclass:: freedombox.diagnostic_check.Result
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Info
|
||||
^^^^
|
||||
|
||||
.. autoclass:: plinth.app.Info
|
||||
.. autoclass:: freedombox.app.Info
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Let's Encrypt
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.letsencrypt.components.LetsEncrypt
|
||||
.. autoclass:: freedombox.modules.letsencrypt.components.LetsEncrypt
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Menu
|
||||
^^^^
|
||||
|
||||
.. autoclass:: plinth.menu.Menu
|
||||
.. autoclass:: freedombox.menu.Menu
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Packages
|
||||
^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.package.Packages
|
||||
.. autoclass:: freedombox.package.Packages
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
StaticFiles
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.web_server.StaticFiles
|
||||
.. autoclass:: freedombox.web_server.StaticFiles
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Users
|
||||
^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.users.components.UsersAndGroups
|
||||
.. autoclass:: freedombox.modules.users.components.UsersAndGroups
|
||||
:members:
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Webserver
|
||||
^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.modules.apache.components.Webserver
|
||||
.. autoclass:: freedombox.modules.apache.components.Webserver
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.modules.apache.components.WebserverRoot
|
||||
.. autoclass:: freedombox.modules.apache.components.WebserverRoot
|
||||
:members:
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Forms
|
||||
-----
|
||||
|
||||
.. autoclass:: plinth.forms.DomainSelectionForm
|
||||
.. autoclass:: freedombox.forms.DomainSelectionForm
|
||||
:members:
|
||||
|
||||
.. autoclass:: plinth.forms.CheckboxSelectMultipleWithReadOnly
|
||||
.. autoclass:: freedombox.forms.CheckboxSelectMultipleWithReadOnly
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Notification
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. autoclass:: plinth.notification.Notification
|
||||
.. autoclass:: freedombox.notification.Notification
|
||||
:members:
|
||||
|
||||
@ -3,5 +3,5 @@
|
||||
Views
|
||||
-----
|
||||
|
||||
.. autoclass:: plinth.views.AppView
|
||||
.. autoclass:: freedombox.views.AppView
|
||||
:members:
|
||||
|
||||
@ -6,56 +6,56 @@ Full Code
|
||||
Transmission app is already included in FreedomBox. Here is the full source for
|
||||
the module for reference.
|
||||
|
||||
plinth/modules/transmission/__init__.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
freedombox/modules/transmission/__init__.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/__init__.py
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/__init__.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/forms.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
freedombox/modules/transmission/forms.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/forms.py
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/forms.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/manifest.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
freedombox/modules/transmission/manifest.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/manifest.py
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/manifest.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/privileged.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/privileged.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/urls.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/urls.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/views.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/views.py
|
||||
:language: python3
|
||||
|
||||
plinth/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission
|
||||
:language: text
|
||||
|
||||
plinth/modules/transmission/data/usr/share/freedombox/etc/apache2/conf-available/transmission-plinth.conf
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/data/usr/share/freedombox/etc/apache2/conf-available/transmission-plinth.conf
|
||||
:language: apache
|
||||
|
||||
plinth/modules/transmission/tests/__init__.py
|
||||
freedombox/modules/transmission/privileged.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../plinth/modules/transmission/tests/__init__.py
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/privileged.py
|
||||
:language: python3
|
||||
|
||||
freedombox/modules/transmission/urls.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/urls.py
|
||||
:language: python3
|
||||
|
||||
freedombox/modules/transmission/views.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/views.py
|
||||
:language: python3
|
||||
|
||||
freedombox/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission
|
||||
:language: text
|
||||
|
||||
freedombox/modules/transmission/data/usr/share/freedombox/etc/apache2/conf-available/transmission-plinth.conf
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/data/usr/share/freedombox/etc/apache2/conf-available/transmission-plinth.conf
|
||||
:language: apache
|
||||
|
||||
freedombox/modules/transmission/tests/__init__.py
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. literalinclude:: ../../../freedombox/modules/transmission/tests/__init__.py
|
||||
:language: python3
|
||||
|
||||
@ -3,11 +3,11 @@
|
||||
Part 4: Components
|
||||
------------------
|
||||
|
||||
Each :class:`~plinth.app.App` contains various :class:`~plinth.app.Component`
|
||||
components that each provide one small functionality needed by the app. Each of
|
||||
these components are instantiated and added to the app as children. The
|
||||
:class:`~plinth.menu.Menu` object added in the previous step is one such
|
||||
component.
|
||||
Each :class:`~freedombox.app.App` contains various
|
||||
:class:`~freedombox.app.Component` components that each provide one small
|
||||
functionality needed by the app. Each of these components are instantiated and
|
||||
added to the app as children. The :class:`~freedombox.menu.Menu` object added in
|
||||
the previous step is one such component.
|
||||
|
||||
Providing basic information about the app
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -20,7 +20,7 @@ function normally.
|
||||
|
||||
from django.utils.translation import gettext_lazy as _
|
||||
|
||||
from plinth import app as app_module
|
||||
from freedombox import app as app_module
|
||||
|
||||
from . import manifest
|
||||
|
||||
@ -44,7 +44,7 @@ needs to be called again. name, icon_filename, description, manual_page,
|
||||
clients, and tags provide information that is shown on the app's main page. The
|
||||
donation_url encourages our users to contribute to upstream projects in order
|
||||
ensure their long term sustainability. More information about the parameters is
|
||||
available in :class:`~plinth.app.Info` class documentation.
|
||||
available in :class:`~freedombox.app.Info` class documentation.
|
||||
|
||||
The description of app should provide basic information on what the app is about
|
||||
and how to use it. It is impractical, however, to explain everything about the
|
||||
@ -82,13 +82,13 @@ running in the system to work. When the app is enabled, the daemon should be
|
||||
enabled. When the app is disabled, the daemon should be disabled. We should also
|
||||
show the status of whether the daemon is running in the app's view. All of these
|
||||
concerns are automatically handled by the framework if a
|
||||
:class:`~plinth.daemon.Daemon` component is added to the app. Let us do that in
|
||||
our app's class.
|
||||
:class:`~freedombox.daemon.Daemon` component is added to the app. Let us do that
|
||||
in our app's class.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.daemon import Daemon
|
||||
from freedombox.daemon import Daemon
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -101,8 +101,8 @@ our app's class.
|
||||
self.add(daemon)
|
||||
|
||||
|
||||
The first argument to instantiate the :class:`~plinth.daemon.Daemon` class is a
|
||||
unique ID. The second is the name of the `systemd
|
||||
The first argument to instantiate the :class:`~freedombox.daemon.Daemon` class
|
||||
is a unique ID. The second is the name of the `systemd
|
||||
<https://www.freedesktop.org/wiki/Software/systemd/>`_ unit file which manages
|
||||
the daemon. The final argument is the list of ports that this daemon listens on.
|
||||
This information is used to check if the daemon is listening on the expected
|
||||
@ -113,14 +113,14 @@ Package management
|
||||
|
||||
Transmission server is installed through a set of packages fetched from Debian
|
||||
package repositories. The packages required for this are passed on to a
|
||||
:class:`~plinth.package.Packages` component which takes care of installing,
|
||||
:class:`~freedombox.package.Packages` component which takes care of installing,
|
||||
upgrading and uninstalling the Debian packages. An app might require one or more
|
||||
Debian packages to be installed.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.package import Packages
|
||||
from freedombox.package import Packages
|
||||
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
@ -146,13 +146,13 @@ write a configuration snippet for Apache, the default web server on FreedomBox.
|
||||
This configuration snippet needs to be activated when our app is enabled. The
|
||||
configuration snippet needs to be deactivated when our app is disabled. All of
|
||||
these concerns are automatically handled by the framework if a
|
||||
:class:`~plinth.modules.apache.components.Webserver` component is added to the
|
||||
app. Let us do that in our app's class.
|
||||
:class:`~freedombox.modules.apache.components.Webserver` component is added to
|
||||
the app. Let us do that in our app's class.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.modules.apache.components import Webserver
|
||||
from freedombox.modules.apache.components import Webserver
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -165,13 +165,13 @@ app. Let us do that in our app's class.
|
||||
self.add(webserver)
|
||||
|
||||
The first argument to instantiate the
|
||||
:class:`~plinth.modules.apache.components.Webserver` class is a unique ID. The
|
||||
second is the name of the Apache2 web server configuration snippet that contains
|
||||
the directives to proxy Transmission web interface via Apache2. We then need to
|
||||
create the configuration file itself in ``transmission-plinth.conf``. The
|
||||
final argument is the list of URLs that the app exposes to the users of the app.
|
||||
This information is used to check if the URLs are accessible as expected when
|
||||
the user requests diagnostic tests on the app.
|
||||
:class:`~freedombox.modules.apache.components.Webserver` class is a unique ID.
|
||||
The second is the name of the Apache2 web server configuration snippet that
|
||||
contains the directives to proxy Transmission web interface via Apache2. We then
|
||||
need to create the configuration file itself in ``transmission-plinth.conf``.
|
||||
The final argument is the list of URLs that the app exposes to the users of the
|
||||
app. This information is used to check if the URLs are accessible as expected
|
||||
when the user requests diagnostic tests on the app.
|
||||
|
||||
Simply creating and shipping a configuration file into ``/etc`` folder creates
|
||||
some hassles. Consider the following scenario: a debian package, either
|
||||
@ -181,13 +181,13 @@ debian package provides a newer version of the configuration file with, say,
|
||||
more tweaks. As a result, a configuration file prompt is shown to the user
|
||||
during package upgrade process. In case of unattended upgrades, the package is
|
||||
not upgraded at all. To avoid such problems, FreedomBox provides the
|
||||
:class:`~plinth.config.DropinConfigs` component. Let us add it in our app's
|
||||
:class:`~freedombox.config.DropinConfigs` component. Let us add it in our app's
|
||||
class.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.config import DropinConfigs
|
||||
from freedombox.config import DropinConfigs
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -200,9 +200,9 @@ class.
|
||||
])
|
||||
self.add(dropin_configs)
|
||||
|
||||
The first argument to instantiate the :class:`~plinth.config.DropinConfigs`
|
||||
The first argument to instantiate the :class:`~freedombox.config.DropinConfigs`
|
||||
class is the unique ID. The second argument is the list of configuration files
|
||||
as paths is ``/etc/``. The :class:`~plinth.config.DropinConfigs` component
|
||||
as paths is ``/etc/``. The :class:`~freedombox.config.DropinConfigs` component
|
||||
requires that a file be shipped into ``/usr/share/freedombox/etc`` instead of
|
||||
``/etc``. The component will handle the creation of a symlink from ``/usr`` path
|
||||
to ``/etc`` path. To ship the file, we can simply create file in the ``data/``
|
||||
@ -231,13 +231,13 @@ special port since the web ports are always kept open. However, it is still good
|
||||
to specify that we operate on http/https ports so that users can be provided
|
||||
this information along with additional information on whether the service is
|
||||
available over Internet. Create the
|
||||
:class:`~plinth.modules.firewall.components.Firewall` component during app
|
||||
:class:`~freedombox.modules.firewall.components.Firewall` component during app
|
||||
initialization.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.modules.firewall.components import Firewall
|
||||
from freedombox.modules.firewall.components import Firewall
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -268,7 +268,7 @@ with the FreedomBox framework in ``__init.py__``.
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.modules.users.components import UsersAndGroups
|
||||
from freedombox.modules.users.components import UsersAndGroups
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -303,12 +303,12 @@ since only they can configure the app. Other users who have access to this app
|
||||
should have a way of discovering the app. This is done by providing a link in
|
||||
the front page of FreedomBox web interface. This is the page that user's see
|
||||
when they visit FreedomBox. To provide this shortcut, a
|
||||
:class:`~plinth.frontpage.Shortcut` component can added to the app.
|
||||
:class:`~freedombox.frontpage.Shortcut` component can added to the app.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth import frontpage
|
||||
from freedombox import frontpage
|
||||
|
||||
group = ('bit-torrent', 'Download files using BitTorrent applications')
|
||||
|
||||
@ -344,15 +344,15 @@ Each app in FreedomBox needs to provide the ability to backup and restore its
|
||||
configuration and data. Apart from providing durability to users' data, this
|
||||
allows the user to migrate from one machine to another. FreedomBox framework
|
||||
provides a component for handling these operations. Create the
|
||||
:class:`~plinth.modules.backups.components.BackupRestore` component during app
|
||||
initialization.
|
||||
:class:`~freedombox.modules.backups.components.BackupRestore` component during
|
||||
app initialization.
|
||||
|
||||
In ``__init__.py``, add:
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth.modules.backups.components import BackupRestore
|
||||
from freedombox.modules.backups.components import BackupRestore
|
||||
|
||||
from . import manifest
|
||||
|
||||
|
||||
@ -101,7 +101,7 @@ the user submits it. Let us implement that in ``views.py``.
|
||||
|
||||
from django.contrib import messages
|
||||
|
||||
from plinth import actions, views
|
||||
from freedombox import actions, views
|
||||
|
||||
from .forms import TransmissionForm
|
||||
|
||||
@ -161,8 +161,8 @@ for transmission daemon. We will do this by creating a file ``privileged.py``.
|
||||
import json
|
||||
import pathlib
|
||||
|
||||
from plinth import action_utils
|
||||
from plinth.actions import privileged
|
||||
from freedombox import action_utils
|
||||
from freedombox.actions import privileged
|
||||
|
||||
_transmission_config = pathlib.Path('/etc/transmission-daemon/settings.json')
|
||||
|
||||
@ -187,8 +187,8 @@ for transmission daemon. We will do this by creating a file ``privileged.py``.
|
||||
action_utils.service_reload('transmission-daemon')
|
||||
|
||||
This is a simple Python3 module but it runs in a separate process with superuser
|
||||
privileges due to the :meth:`plinth.actions.privileged` decorator. All such
|
||||
privileges due to the :meth:`freedombox.actions.privileged` decorator. All such
|
||||
methods must have full type annotations for the method parameters. Further, the
|
||||
parameters and return value must be JSON serializable. It may use various helper
|
||||
utilities provided by the FreedomBox framework in :obj:`plinth.action_utils` to
|
||||
easily perform it's duties.
|
||||
utilities provided by the FreedomBox framework in :obj:`freedombox.action_utils`
|
||||
to easily perform it's duties.
|
||||
|
||||
@ -13,9 +13,9 @@ framework as part of the components used by an app. FreedomBox takes care of
|
||||
calling the diagnostics method and displaying the list in a formatted manner.
|
||||
|
||||
To implement additional diagnostic tests on top of those provided by the
|
||||
framework, the method :meth:`plinth.app.App.diagnose` has to be overridden or in
|
||||
a component that belongs to the app, the method
|
||||
:meth:`plinth.app.Component.diagnose` has to be overridden. The methods must
|
||||
framework, the method :meth:`freedombox.app.App.diagnose` has to be overridden
|
||||
or in a component that belongs to the app, the method
|
||||
:meth:`freedombox.app.Component.diagnose` has to be overridden. The methods must
|
||||
return a list in which each item is the result of a test performed. The item
|
||||
itself is a two-tuple containing the display name of the test followed by the
|
||||
result as ``passed``, ``failed`` or ``error``.
|
||||
@ -36,7 +36,7 @@ result as ``passed``, ``failed`` or ``error``.
|
||||
The user can trigger the diagnostics test by going to **System -> Diagnostics**
|
||||
page. This runs diagnostics for all the applications. Users can also run
|
||||
diagnostics specifically for this app from the app's page. A diagnostics menu
|
||||
item is shown by the :class:`plinth.views.AppView` and `app.html` template
|
||||
item is shown by the :class:`freedombox.views.AppView` and `app.html` template
|
||||
automatically when ``diagnose()`` method is overridden in the app or a
|
||||
component.
|
||||
|
||||
|
||||
@ -11,8 +11,8 @@ Creating the project structure
|
||||
Create a directory structure as follows with empty files. We will fill them up
|
||||
in a step-by-step manner::
|
||||
|
||||
─┬ <plinth_root>/
|
||||
└─┬ plinth/
|
||||
─┬ <freedombox_root>/
|
||||
└─┬ freedombox/
|
||||
└─┬ modules/
|
||||
└─┬ transmission/
|
||||
├─ __init__.py
|
||||
@ -41,46 +41,46 @@ The file ``__init__.py`` indicates that the directory in which it is present is
|
||||
a Python module. For now, it is an empty file.
|
||||
|
||||
FreedomBox's build system will automatically install the
|
||||
``plinth/modules/transmission`` directory (along with other files described
|
||||
``freedombox/modules/transmission`` directory (along with other files described
|
||||
later) to an appropriate location. If you are creating an app that stays
|
||||
independent and outside of FreedomBox source tree, then build system in your
|
||||
source tree will need to install it to a proper location on the system. The
|
||||
``plinth/modules/`` directory is a Python3 `namespace package
|
||||
``freedombox/modules/`` directory is a Python3 `namespace package
|
||||
<https://www.python.org/dev/peps/pep-0420/>`_. So, you can install it with the
|
||||
``plinth/modules/`` directory structure into any Python path and still be
|
||||
discovered as ``plinth.modules.*``.
|
||||
``freedombox/modules/`` directory structure into any Python path and still be
|
||||
discovered as ``freedombox.modules.*``.
|
||||
|
||||
Tell FreedomBox that our app exists
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The first thing to do is tell FreedomBox that our app exists. This is done by
|
||||
writing a small file with the Python import path to our app and placing it in
|
||||
``plinth/modules/transmission/data/usr/share/freedombox/modules-enabled/``. Let
|
||||
us create this file ``transmission``:
|
||||
``freedombox/modules/transmission/data/usr/share/freedombox/modules-enabled/``.
|
||||
Let us create this file ``transmission``:
|
||||
|
||||
.. code-block:: text
|
||||
:caption: ``plinth/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission``
|
||||
:caption: ``freedombox/modules/transmission/data/usr/share/freedombox/modules-enabled/transmission``
|
||||
|
||||
plinth.modules.transmission
|
||||
freedombox.modules.transmission
|
||||
|
||||
This file is automatically installed to
|
||||
``/usr/share/freedombox/modules-enabled/`` by FreedomBox's build system. If we
|
||||
are writing a module that resides independently outside the FreedomBox's source
|
||||
code, the setup script will need to copy it to the target location. Further, it
|
||||
is not necessary for the app to be part of the ``plinth.modules`` namespace. It
|
||||
can, for example, be ``freedombox_transmission``.
|
||||
is not necessary for the app to be part of the ``freedombox.modules`` namespace.
|
||||
It can, for example, be ``freedombox_transmission``.
|
||||
|
||||
Creating the App class
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In the FreedomBox framework, each app must be a class derived from the
|
||||
:class:`plinth.app.App`. Let us do that in ``__init__.py``. We will fill up the
|
||||
class later.
|
||||
:class:`freedombox.app.App`. Let us do that in ``__init__.py``. We will fill up
|
||||
the class later.
|
||||
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth import app as app_module
|
||||
from freedombox import app as app_module
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
"""FreedomBox app for Transmission."""
|
||||
|
||||
@ -22,7 +22,7 @@ write the following:
|
||||
]
|
||||
|
||||
This routes the ``/apps/transmission/`` URL to a view called
|
||||
``TransmissionAppView`` defined in ``plinth/modules/transmission/views.py``.
|
||||
``TransmissionAppView`` defined in ``freedombox/modules/transmission/views.py``.
|
||||
This is no different than how routing URLs is done in Django. See :doc:`Django
|
||||
URL dispatcher <django:topics/http/urls>` for more information.
|
||||
|
||||
@ -36,7 +36,7 @@ a link in FreedomBox web interface. Let us add a link in the apps list. In
|
||||
.. code-block:: python3
|
||||
:caption: ``__init__.py``
|
||||
|
||||
from plinth import menu
|
||||
from freedombox import menu
|
||||
|
||||
class TransmissionApp(app_module.App):
|
||||
...
|
||||
@ -63,7 +63,7 @@ menu item we want to present.
|
||||
|
||||
* The third parameter is the name of the icon to use when showing the menu
|
||||
item. An SVG file and a PNG should be created in the
|
||||
``plinth/modules/transmission/static/icons/`` directory.
|
||||
``freedombox/modules/transmission/static/icons/`` directory.
|
||||
|
||||
* The fourth parameter is the list of tags to show on the menu item.
|
||||
|
||||
@ -87,15 +87,15 @@ view to show the app page for our app. In ``views.py``, let us add a view.
|
||||
.. code-block:: python3
|
||||
:caption: ``views.py``
|
||||
|
||||
from plinth import views
|
||||
from plinth.modules import transmission
|
||||
from freedombox import views
|
||||
from freedombox.modules import transmission
|
||||
|
||||
class TransmissionAppView(views.AppView):
|
||||
"""Serve configuration page."""
|
||||
app_id = 'transmission'
|
||||
|
||||
The base view :class:`~plinth.views.AppView` takes care of a lot of details for
|
||||
us. First, it shows basic information about the app like name, description,
|
||||
The base view :class:`~freedombox.views.AppView` takes care of a lot of details
|
||||
for us. First, it shows basic information about the app like name, description,
|
||||
desktop/mobiles clients for the service (described later), link to the manual
|
||||
page (described later), link to diagnostics button, etc. Then it shows the
|
||||
status of the app whether it is running and can also present a form for
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user