nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-09-19 04:59:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/dev: Update developer documentation with new import path

Browse Source 
Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org>
Reviewed-by: James Valleroy <jvalleroy@mailbox.org>
This commit is contained in:
Sunil Mohan Adapa 2026-08-17 14:28:32 -07:00 committed by James Valleroy
parent 5e17a84c8a
commit d128836d2f
No known key found for this signature in database
GPG Key ID: 77C0C75E7B650808
30 changed files with 151 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/dev/conf.py
View File

@ -20,7 +20,7 @@ from datetime import datetime
import django import django
sys.path.insert(0, os.path.abspath('../../')) sys.path.insert(0, os.path.abspath('../../'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'plinth.settings' os.environ['DJANGO_SETTINGS_MODULE'] = 'freedombox.settings'
django.setup() django.setup()
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------

2
doc/dev/reference/action_utils.rst
View File

@ -6,5 +6,5 @@ Action Utils
Several utilities to help with the implementation of actions and diagnostic Several utilities to help with the implementation of actions and diagnostic
tests are implemented in this module. tests are implemented in this module.
.. automodule:: plinth.action_utils .. automodule:: freedombox.action_utils
:members: :members:

18
doc/dev/reference/actions.rst
View File

@ -1,16 +1,14 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. SPDX-License-Identifier: CC-BY-SA-4.0
Actions Privileged Actions
^^^^^^^ ^^^^^^^^^^^^^^^^^^
FreedomBox's web front does not directly change any aspect of the underlying FreedomBox Service performs most changes to the underlying operating system
operating system. Instead, it calls upon **actions**, as shell commands. Actions using remote calls into the **freedombox-privileged** daemon or other daemons
live in ``/usr/share/plinth/actions`` directory. They require no interaction such as NetworkManager and UDisks.
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.
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 :members: privileged

2
doc/dev/reference/app.rst
View File

@ -3,5 +3,5 @@
App App
--- ---
.. autoclass:: plinth.app.App .. autoclass:: freedombox.app.App
:members: :members:

2
doc/dev/reference/components/backups.rst
View File

@ -3,5 +3,5 @@
Backups Backups
^^^^^^^ ^^^^^^^
.. autoclass:: plinth.modules.backups.components.BackupRestore .. autoclass:: freedombox.modules.backups.components.BackupRestore
:members: :members:

2
doc/dev/reference/components/config.rst
View File

@ -3,5 +3,5 @@
Configuration Configuration
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
.. autoclass:: plinth.config.DropinConfigs .. autoclass:: freedombox.config.DropinConfigs
:members: :members:

2
doc/dev/reference/components/container.rst
View File

@ -3,5 +3,5 @@
Container Container
^^^^^^^^^ ^^^^^^^^^
.. autoclass:: plinth.container.Container .. autoclass:: freedombox.container.Container
:members: :members:

4
doc/dev/reference/components/coturn.rst
View File

@ -3,8 +3,8 @@
Coturn Coturn
^^^^^^ ^^^^^^
.. autoclass:: plinth.modules.coturn.components.TurnConsumer .. autoclass:: freedombox.modules.coturn.components.TurnConsumer
:members: :members:
.. autoclass:: plinth.modules.coturn.components.TurnConfiguration .. autoclass:: freedombox.modules.coturn.components.TurnConfiguration
:members: :members:

6
doc/dev/reference/components/daemon.rst
View File

@ -3,11 +3,11 @@
Daemon Daemon
^^^^^^ ^^^^^^
.. autoclass:: plinth.daemon.Daemon .. autoclass:: freedombox.daemon.Daemon
:members: :members:
.. autoclass:: plinth.daemon.RelatedDaemon .. autoclass:: freedombox.daemon.RelatedDaemon
:members: :members:
.. autoclass:: plinth.daemon.SharedDaemon .. autoclass:: freedombox.daemon.SharedDaemon
:members: :members:

4
doc/dev/reference/components/domain.rst
View File

@ -3,8 +3,8 @@
Domain Name Domain Name
^^^^^^^^^^^ ^^^^^^^^^^^
.. autoclass:: plinth.modules.names.components.DomainName .. autoclass:: freedombox.modules.names.components.DomainName
:members: :members:
.. autoclass:: plinth.modules.names.components.DomainType .. autoclass:: freedombox.modules.names.components.DomainType
:members: :members:

2
doc/dev/reference/components/enablestate.rst
View File

@ -3,5 +3,5 @@
EnableState EnableState
^^^^^^^^^^^ ^^^^^^^^^^^
.. autoclass:: plinth.app.EnableState .. autoclass:: freedombox.app.EnableState
:members: :members:

4
doc/dev/reference/components/firewall.rst
View File

@ -3,8 +3,8 @@
Firewall Firewall
^^^^^^^^ ^^^^^^^^
.. autoclass:: plinth.modules.firewall.components.Firewall .. autoclass:: freedombox.modules.firewall.components.Firewall
:members: :members:
.. autoclass:: plinth.modules.firewall.components.FirewallLocalProtection .. autoclass:: freedombox.modules.firewall.components.FirewallLocalProtection
:members: :members:

2
doc/dev/reference/components/frontpage.rst
View File

@ -3,5 +3,5 @@
Frontpage Frontpage
^^^^^^^^^ ^^^^^^^^^
.. autoclass:: plinth.frontpage.Shortcut .. autoclass:: freedombox.frontpage.Shortcut
:members: :members:

10
doc/dev/reference/components/index.rst
View File

@ -27,20 +27,20 @@ Components
Base Classes Base Classes
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. autoclass:: plinth.app.Component .. autoclass:: freedombox.app.Component
:members: :members:
.. autoclass:: plinth.app.LeaderComponent .. autoclass:: freedombox.app.LeaderComponent
:members: :members:
.. autoclass:: plinth.app.FollowerComponent .. autoclass:: freedombox.app.FollowerComponent
:members: :members:
Other Classes Other Classes
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
.. autoclass:: plinth.diagnostic_check.DiagnosticCheck .. autoclass:: freedombox.diagnostic_check.DiagnosticCheck
:members: :members:
.. autoclass:: plinth.diagnostic_check.Result .. autoclass:: freedombox.diagnostic_check.Result
:members: :members:

2
doc/dev/reference/components/info.rst
View File

@ -3,5 +3,5 @@
Info Info
^^^^ ^^^^
.. autoclass:: plinth.app.Info .. autoclass:: freedombox.app.Info
:members: :members:

2
doc/dev/reference/components/letsencrypt.rst
View File

@ -3,5 +3,5 @@
Let's Encrypt Let's Encrypt
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
.. autoclass:: plinth.modules.letsencrypt.components.LetsEncrypt .. autoclass:: freedombox.modules.letsencrypt.components.LetsEncrypt
:members: :members:

2
doc/dev/reference/components/menu.rst
View File

@ -3,5 +3,5 @@
Menu Menu
^^^^ ^^^^
.. autoclass:: plinth.menu.Menu .. autoclass:: freedombox.menu.Menu
:members: :members:

2
doc/dev/reference/components/packages.rst
View File

@ -3,5 +3,5 @@
Packages Packages
^^^^^^^^ ^^^^^^^^
.. autoclass:: plinth.package.Packages .. autoclass:: freedombox.package.Packages
:members: :members:

2
doc/dev/reference/components/staticfiles.rst
View File

@ -3,5 +3,5 @@
StaticFiles StaticFiles
^^^^^^^^^^^ ^^^^^^^^^^^
.. autoclass:: plinth.web_server.StaticFiles .. autoclass:: freedombox.web_server.StaticFiles
:members: :members:

2
doc/dev/reference/components/users.rst
View File

@ -3,5 +3,5 @@
Users Users
^^^^^ ^^^^^
.. autoclass:: plinth.modules.users.components.UsersAndGroups .. autoclass:: freedombox.modules.users.components.UsersAndGroups
:members: :members:

4
doc/dev/reference/components/webserver.rst
View File

@ -3,8 +3,8 @@
Webserver Webserver
^^^^^^^^^ ^^^^^^^^^
.. autoclass:: plinth.modules.apache.components.Webserver .. autoclass:: freedombox.modules.apache.components.Webserver
:members: :members:
.. autoclass:: plinth.modules.apache.components.WebserverRoot .. autoclass:: freedombox.modules.apache.components.WebserverRoot
:members: :members:

4
doc/dev/reference/forms.rst
View File

@ -3,8 +3,8 @@
Forms Forms
----- -----
.. autoclass:: plinth.forms.DomainSelectionForm .. autoclass:: freedombox.forms.DomainSelectionForm
:members: :members:
.. autoclass:: plinth.forms.CheckboxSelectMultipleWithReadOnly .. autoclass:: freedombox.forms.CheckboxSelectMultipleWithReadOnly
:members: :members:

2
doc/dev/reference/notifications.rst
View File

@ -3,5 +3,5 @@
Notification Notification
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. autoclass:: plinth.notification.Notification .. autoclass:: freedombox.notification.Notification
:members: :members:

2
doc/dev/reference/views.rst
View File

@ -3,5 +3,5 @@
Views Views
----- -----
.. autoclass:: plinth.views.AppView .. autoclass:: freedombox.views.AppView
:members: :members:

82
doc/dev/tutorial/code.rst
View File

@ -6,56 +6,56 @@ Full Code
Transmission app is already included in FreedomBox. Here is the full source for Transmission app is already included in FreedomBox. Here is the full source for
the module for reference. 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 :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 :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 :language: python3
plinth/modules/transmission/privileged.py freedombox/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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. 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 :language: python3

72
doc/dev/tutorial/components.rst
View File

@ -3,11 +3,11 @@
Part 4: Components Part 4: Components
------------------ ------------------
Each :class:`~plinth.app.App` contains various :class:`~plinth.app.Component` Each :class:`~freedombox.app.App` contains various
components that each provide one small functionality needed by the app. Each of :class:`~freedombox.app.Component` components that each provide one small
these components are instantiated and added to the app as children. The functionality needed by the app. Each of these components are instantiated and
:class:`~plinth.menu.Menu` object added in the previous step is one such added to the app as children. The :class:`~freedombox.menu.Menu` object added in
component. the previous step is one such component.
Providing basic information about the app Providing basic information about the app
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -20,7 +20,7 @@ function normally.
from django.utils.translation import gettext_lazy as _ 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 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 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 donation_url encourages our users to contribute to upstream projects in order
ensure their long term sustainability. More information about the parameters is 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 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 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 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 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 concerns are automatically handled by the framework if a
:class:`~plinth.daemon.Daemon` component is added to the app. Let us do that in :class:`~freedombox.daemon.Daemon` component is added to the app. Let us do that
our app's class. in our app's class.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.daemon import Daemon from freedombox.daemon import Daemon
class TransmissionApp(app_module.App): class TransmissionApp(app_module.App):
... ...
@ -101,8 +101,8 @@ our app's class.
self.add(daemon) self.add(daemon)
The first argument to instantiate the :class:`~plinth.daemon.Daemon` class is a The first argument to instantiate the :class:`~freedombox.daemon.Daemon` class
unique ID. The second is the name of the `systemd is a unique ID. The second is the name of the `systemd
<https://www.freedesktop.org/wiki/Software/systemd/>`_ unit file which manages <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. 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 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 Transmission server is installed through a set of packages fetched from Debian
package repositories. The packages required for this are passed on to a 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 upgrading and uninstalling the Debian packages. An app might require one or more
Debian packages to be installed. Debian packages to be installed.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.package import Packages from freedombox.package import Packages
class TransmissionApp(app_module.App): 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 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 configuration snippet needs to be deactivated when our app is disabled. All of
these concerns are automatically handled by the framework if a these concerns are automatically handled by the framework if a
:class:`~plinth.modules.apache.components.Webserver` component is added to the :class:`~freedombox.modules.apache.components.Webserver` component is added to
app. Let us do that in our app's class. the app. Let us do that in our app's class.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.modules.apache.components import Webserver from freedombox.modules.apache.components import Webserver
class TransmissionApp(app_module.App): class TransmissionApp(app_module.App):
... ...
@ -165,13 +165,13 @@ app. Let us do that in our app's class.
self.add(webserver) self.add(webserver)
The first argument to instantiate the The first argument to instantiate the
:class:`~plinth.modules.apache.components.Webserver` class is a unique ID. The :class:`~freedombox.modules.apache.components.Webserver` class is a unique ID.
second is the name of the Apache2 web server configuration snippet that contains The second is the name of the Apache2 web server configuration snippet that
the directives to proxy Transmission web interface via Apache2. We then need to contains the directives to proxy Transmission web interface via Apache2. We then
create the configuration file itself in ``transmission-plinth.conf``. The need to create the configuration file itself in ``transmission-plinth.conf``.
final argument is the list of URLs that the app exposes to the users of the app. The final argument is the list of URLs that the app exposes to the users of the
This information is used to check if the URLs are accessible as expected when app. This information is used to check if the URLs are accessible as expected
the user requests diagnostic tests on the app. when the user requests diagnostic tests on the app.
Simply creating and shipping a configuration file into ``/etc`` folder creates Simply creating and shipping a configuration file into ``/etc`` folder creates
some hassles. Consider the following scenario: a debian package, either 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 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 during package upgrade process. In case of unattended upgrades, the package is
not upgraded at all. To avoid such problems, FreedomBox provides the 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. class.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.config import DropinConfigs from freedombox.config import DropinConfigs
class TransmissionApp(app_module.App): class TransmissionApp(app_module.App):
... ...
@ -200,9 +200,9 @@ class.
]) ])
self.add(dropin_configs) 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 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 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 ``/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/`` 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 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 this information along with additional information on whether the service is
available over Internet. Create the available over Internet. Create the
:class:`~plinth.modules.firewall.components.Firewall` component during app :class:`~freedombox.modules.firewall.components.Firewall` component during app
initialization. initialization.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.modules.firewall.components import Firewall from freedombox.modules.firewall.components import Firewall
class TransmissionApp(app_module.App): class TransmissionApp(app_module.App):
... ...
@ -268,7 +268,7 @@ with the FreedomBox framework in ``__init.py__``.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.modules.users.components import UsersAndGroups from freedombox.modules.users.components import UsersAndGroups
class TransmissionApp(app_module.App): 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 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 the front page of FreedomBox web interface. This is the page that user's see
when they visit FreedomBox. To provide this shortcut, a 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 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth import frontpage from freedombox import frontpage
group = ('bit-torrent', 'Download files using BitTorrent applications') 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 configuration and data. Apart from providing durability to users' data, this
allows the user to migrate from one machine to another. FreedomBox framework allows the user to migrate from one machine to another. FreedomBox framework
provides a component for handling these operations. Create the provides a component for handling these operations. Create the
:class:`~plinth.modules.backups.components.BackupRestore` component during app :class:`~freedombox.modules.backups.components.BackupRestore` component during
initialization. app initialization.
In ``__init__.py``, add: In ``__init__.py``, add:
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth.modules.backups.components import BackupRestore from freedombox.modules.backups.components import BackupRestore
from . import manifest from . import manifest

12
doc/dev/tutorial/customizing.rst
View File

@ -101,7 +101,7 @@ the user submits it. Let us implement that in ``views.py``.
from django.contrib import messages from django.contrib import messages
from plinth import actions, views from freedombox import actions, views
from .forms import TransmissionForm from .forms import TransmissionForm
@ -161,8 +161,8 @@ for transmission daemon. We will do this by creating a file ``privileged.py``.
import json import json
import pathlib import pathlib
from plinth import action_utils from freedombox import action_utils
from plinth.actions import privileged from freedombox.actions import privileged
_transmission_config = pathlib.Path('/etc/transmission-daemon/settings.json') _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') action_utils.service_reload('transmission-daemon')
This is a simple Python3 module but it runs in a separate process with superuser 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 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 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 utilities provided by the FreedomBox framework in :obj:`freedombox.action_utils`
easily perform it's duties. to easily perform it's duties.

8
doc/dev/tutorial/other.rst
View File

@ -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. calling the diagnostics method and displaying the list in a formatted manner.
To implement additional diagnostic tests on top of those provided by the 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 framework, the method :meth:`freedombox.app.App.diagnose` has to be overridden
a component that belongs to the app, the method or in a component that belongs to the app, the method
:meth:`plinth.app.Component.diagnose` has to be overridden. The methods must :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 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 itself is a two-tuple containing the display name of the test followed by the
result as ``passed``, ``failed`` or ``error``. 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** The user can trigger the diagnostics test by going to **System -> Diagnostics**
page. This runs diagnostics for all the applications. Users can also run 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 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 automatically when ``diagnose()`` method is overridden in the app or a
component. component.

30
doc/dev/tutorial/skeleton.rst
View File

@ -11,8 +11,8 @@ Creating the project structure
Create a directory structure as follows with empty files. We will fill them up Create a directory structure as follows with empty files. We will fill them up
in a step-by-step manner:: in a step-by-step manner::
─┬ <plinth_root>/ ─┬ <freedombox_root>/
└─┬ plinth/ └─┬ freedombox/
└─┬ modules/ └─┬ modules/
└─┬ transmission/ └─┬ transmission/
├─ __init__.py ├─ __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. a Python module. For now, it is an empty file.
FreedomBox's build system will automatically install the 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 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 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 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 <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 ``freedombox/modules/`` directory structure into any Python path and still be
discovered as ``plinth.modules.*``. discovered as ``freedombox.modules.*``.
Tell FreedomBox that our app exists Tell FreedomBox that our app exists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The first thing to do is tell FreedomBox that our app exists. This is done by 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 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 ``freedombox/modules/transmission/data/usr/share/freedombox/modules-enabled/``.
us create this file ``transmission``: Let us create this file ``transmission``:
.. code-block:: text .. 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 This file is automatically installed to
``/usr/share/freedombox/modules-enabled/`` by FreedomBox's build system. If we ``/usr/share/freedombox/modules-enabled/`` by FreedomBox's build system. If we
are writing a module that resides independently outside the FreedomBox's source 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 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 is not necessary for the app to be part of the ``freedombox.modules`` namespace.
can, for example, be ``freedombox_transmission``. It can, for example, be ``freedombox_transmission``.
Creating the App class Creating the App class
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
In the FreedomBox framework, each app must be a class derived from the 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:`freedombox.app.App`. Let us do that in ``__init__.py``. We will fill up
class later. the class later.
.. code-block:: python3 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth import app as app_module from freedombox import app as app_module
class TransmissionApp(app_module.App): class TransmissionApp(app_module.App):
"""FreedomBox app for Transmission.""" """FreedomBox app for Transmission."""

14
doc/dev/tutorial/view.rst
View File

@ -22,7 +22,7 @@ write the following:
] ]
This routes the ``/apps/transmission/`` URL to a view called 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 This is no different than how routing URLs is done in Django. See :doc:`Django
URL dispatcher <django:topics/http/urls>` for more information. 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 .. code-block:: python3
:caption: ``__init__.py`` :caption: ``__init__.py``
from plinth import menu from freedombox import menu
class TransmissionApp(app_module.App): 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 * 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 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. * 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 .. code-block:: python3
:caption: ``views.py`` :caption: ``views.py``
from plinth import views from freedombox import views
from plinth.modules import transmission from freedombox.modules import transmission
class TransmissionAppView(views.AppView): class TransmissionAppView(views.AppView):
"""Serve configuration page.""" """Serve configuration page."""
app_id = 'transmission' app_id = 'transmission'
The base view :class:`~plinth.views.AppView` takes care of a lot of details for The base view :class:`~freedombox.views.AppView` takes care of a lot of details
us. First, it shows basic information about the app like name, description, 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 desktop/mobiles clients for the service (described later), link to the manual
page (described later), link to diagnostics button, etc. Then it shows the 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 status of the app whether it is running and can also present a form for