diff --git a/doc/dev/conf.py b/doc/dev/conf.py index a32dd2fe8..5a279295f 100644 --- a/doc/dev/conf.py +++ b/doc/dev/conf.py @@ -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 ----------------------------------------------------- diff --git a/doc/dev/reference/action_utils.rst b/doc/dev/reference/action_utils.rst index 92c9c565d..db049bb31 100644 --- a/doc/dev/reference/action_utils.rst +++ b/doc/dev/reference/action_utils.rst @@ -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: diff --git a/doc/dev/reference/actions.rst b/doc/dev/reference/actions.rst index 4ace1950c..239049864 100644 --- a/doc/dev/reference/actions.rst +++ b/doc/dev/reference/actions.rst @@ -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 diff --git a/doc/dev/reference/app.rst b/doc/dev/reference/app.rst index 45f5c1c35..f00aa685d 100644 --- a/doc/dev/reference/app.rst +++ b/doc/dev/reference/app.rst @@ -3,5 +3,5 @@ App --- -.. autoclass:: plinth.app.App +.. autoclass:: freedombox.app.App :members: diff --git a/doc/dev/reference/components/backups.rst b/doc/dev/reference/components/backups.rst index 0afed3842..2f012e125 100644 --- a/doc/dev/reference/components/backups.rst +++ b/doc/dev/reference/components/backups.rst @@ -3,5 +3,5 @@ Backups ^^^^^^^ -.. autoclass:: plinth.modules.backups.components.BackupRestore +.. autoclass:: freedombox.modules.backups.components.BackupRestore :members: diff --git a/doc/dev/reference/components/config.rst b/doc/dev/reference/components/config.rst index a4611827a..0123eb951 100644 --- a/doc/dev/reference/components/config.rst +++ b/doc/dev/reference/components/config.rst @@ -3,5 +3,5 @@ Configuration ^^^^^^^^^^^^^ -.. autoclass:: plinth.config.DropinConfigs +.. autoclass:: freedombox.config.DropinConfigs :members: diff --git a/doc/dev/reference/components/container.rst b/doc/dev/reference/components/container.rst index 697a196f0..a491c5905 100644 --- a/doc/dev/reference/components/container.rst +++ b/doc/dev/reference/components/container.rst @@ -3,5 +3,5 @@ Container ^^^^^^^^^ -.. autoclass:: plinth.container.Container +.. autoclass:: freedombox.container.Container :members: diff --git a/doc/dev/reference/components/coturn.rst b/doc/dev/reference/components/coturn.rst index 95cf737ba..22150a527 100644 --- a/doc/dev/reference/components/coturn.rst +++ b/doc/dev/reference/components/coturn.rst @@ -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: diff --git a/doc/dev/reference/components/daemon.rst b/doc/dev/reference/components/daemon.rst index 69ef72786..884bc2ed6 100644 --- a/doc/dev/reference/components/daemon.rst +++ b/doc/dev/reference/components/daemon.rst @@ -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: diff --git a/doc/dev/reference/components/domain.rst b/doc/dev/reference/components/domain.rst index 884f918a8..74d388e50 100644 --- a/doc/dev/reference/components/domain.rst +++ b/doc/dev/reference/components/domain.rst @@ -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: diff --git a/doc/dev/reference/components/enablestate.rst b/doc/dev/reference/components/enablestate.rst index 056432a57..83ff865dd 100644 --- a/doc/dev/reference/components/enablestate.rst +++ b/doc/dev/reference/components/enablestate.rst @@ -3,5 +3,5 @@ EnableState ^^^^^^^^^^^ -.. autoclass:: plinth.app.EnableState +.. autoclass:: freedombox.app.EnableState :members: diff --git a/doc/dev/reference/components/firewall.rst b/doc/dev/reference/components/firewall.rst index eece5bda1..51d74c848 100644 --- a/doc/dev/reference/components/firewall.rst +++ b/doc/dev/reference/components/firewall.rst @@ -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: diff --git a/doc/dev/reference/components/frontpage.rst b/doc/dev/reference/components/frontpage.rst index 5e185177f..f95b8a814 100644 --- a/doc/dev/reference/components/frontpage.rst +++ b/doc/dev/reference/components/frontpage.rst @@ -3,5 +3,5 @@ Frontpage ^^^^^^^^^ -.. autoclass:: plinth.frontpage.Shortcut +.. autoclass:: freedombox.frontpage.Shortcut :members: diff --git a/doc/dev/reference/components/index.rst b/doc/dev/reference/components/index.rst index be6419544..7660000ec 100644 --- a/doc/dev/reference/components/index.rst +++ b/doc/dev/reference/components/index.rst @@ -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: diff --git a/doc/dev/reference/components/info.rst b/doc/dev/reference/components/info.rst index 827430fed..bb489073a 100644 --- a/doc/dev/reference/components/info.rst +++ b/doc/dev/reference/components/info.rst @@ -3,5 +3,5 @@ Info ^^^^ -.. autoclass:: plinth.app.Info +.. autoclass:: freedombox.app.Info :members: diff --git a/doc/dev/reference/components/letsencrypt.rst b/doc/dev/reference/components/letsencrypt.rst index 84c423806..42347839d 100644 --- a/doc/dev/reference/components/letsencrypt.rst +++ b/doc/dev/reference/components/letsencrypt.rst @@ -3,5 +3,5 @@ Let's Encrypt ^^^^^^^^^^^^^ -.. autoclass:: plinth.modules.letsencrypt.components.LetsEncrypt +.. autoclass:: freedombox.modules.letsencrypt.components.LetsEncrypt :members: diff --git a/doc/dev/reference/components/menu.rst b/doc/dev/reference/components/menu.rst index 9bb682c5a..3f41e8397 100644 --- a/doc/dev/reference/components/menu.rst +++ b/doc/dev/reference/components/menu.rst @@ -3,5 +3,5 @@ Menu ^^^^ -.. autoclass:: plinth.menu.Menu +.. autoclass:: freedombox.menu.Menu :members: diff --git a/doc/dev/reference/components/packages.rst b/doc/dev/reference/components/packages.rst index 6ae4f77fb..436fc5cf5 100644 --- a/doc/dev/reference/components/packages.rst +++ b/doc/dev/reference/components/packages.rst @@ -3,5 +3,5 @@ Packages ^^^^^^^^ -.. autoclass:: plinth.package.Packages +.. autoclass:: freedombox.package.Packages :members: diff --git a/doc/dev/reference/components/staticfiles.rst b/doc/dev/reference/components/staticfiles.rst index 92421f7d7..f1bf3b87a 100644 --- a/doc/dev/reference/components/staticfiles.rst +++ b/doc/dev/reference/components/staticfiles.rst @@ -3,5 +3,5 @@ StaticFiles ^^^^^^^^^^^ -.. autoclass:: plinth.web_server.StaticFiles +.. autoclass:: freedombox.web_server.StaticFiles :members: diff --git a/doc/dev/reference/components/users.rst b/doc/dev/reference/components/users.rst index 88e09d17f..5d2ae10a4 100644 --- a/doc/dev/reference/components/users.rst +++ b/doc/dev/reference/components/users.rst @@ -3,5 +3,5 @@ Users ^^^^^ -.. autoclass:: plinth.modules.users.components.UsersAndGroups +.. autoclass:: freedombox.modules.users.components.UsersAndGroups :members: diff --git a/doc/dev/reference/components/webserver.rst b/doc/dev/reference/components/webserver.rst index 1a42cd199..bdd5ac32b 100644 --- a/doc/dev/reference/components/webserver.rst +++ b/doc/dev/reference/components/webserver.rst @@ -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: diff --git a/doc/dev/reference/forms.rst b/doc/dev/reference/forms.rst index bb3a8ccd4..da9be7937 100644 --- a/doc/dev/reference/forms.rst +++ b/doc/dev/reference/forms.rst @@ -3,8 +3,8 @@ Forms ----- -.. autoclass:: plinth.forms.DomainSelectionForm +.. autoclass:: freedombox.forms.DomainSelectionForm :members: -.. autoclass:: plinth.forms.CheckboxSelectMultipleWithReadOnly +.. autoclass:: freedombox.forms.CheckboxSelectMultipleWithReadOnly :members: diff --git a/doc/dev/reference/notifications.rst b/doc/dev/reference/notifications.rst index 5f6a422be..5499fdff6 100644 --- a/doc/dev/reference/notifications.rst +++ b/doc/dev/reference/notifications.rst @@ -3,5 +3,5 @@ Notification ^^^^^^^^^^^^ -.. autoclass:: plinth.notification.Notification +.. autoclass:: freedombox.notification.Notification :members: diff --git a/doc/dev/reference/views.rst b/doc/dev/reference/views.rst index d7c99aaf2..11395cc29 100644 --- a/doc/dev/reference/views.rst +++ b/doc/dev/reference/views.rst @@ -3,5 +3,5 @@ Views ----- -.. autoclass:: plinth.views.AppView +.. autoclass:: freedombox.views.AppView :members: diff --git a/doc/dev/tutorial/code.rst b/doc/dev/tutorial/code.rst index 7ef02c459..8a852a94c 100644 --- a/doc/dev/tutorial/code.rst +++ b/doc/dev/tutorial/code.rst @@ -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 diff --git a/doc/dev/tutorial/components.rst b/doc/dev/tutorial/components.rst index 4eda87356..0c15eddb7 100644 --- a/doc/dev/tutorial/components.rst +++ b/doc/dev/tutorial/components.rst @@ -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 `_ 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 diff --git a/doc/dev/tutorial/customizing.rst b/doc/dev/tutorial/customizing.rst index 5b0aadd2c..aeabc09fe 100644 --- a/doc/dev/tutorial/customizing.rst +++ b/doc/dev/tutorial/customizing.rst @@ -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. diff --git a/doc/dev/tutorial/other.rst b/doc/dev/tutorial/other.rst index f4ca0ab40..8f6e16aea 100644 --- a/doc/dev/tutorial/other.rst +++ b/doc/dev/tutorial/other.rst @@ -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. diff --git a/doc/dev/tutorial/skeleton.rst b/doc/dev/tutorial/skeleton.rst index e8793ce7b..4ef397d63 100644 --- a/doc/dev/tutorial/skeleton.rst +++ b/doc/dev/tutorial/skeleton.rst @@ -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/ + ─┬ / + └─┬ 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 `_. 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.""" diff --git a/doc/dev/tutorial/view.rst b/doc/dev/tutorial/view.rst index aa7cb4332..f0d0f7e55 100644 --- a/doc/dev/tutorial/view.rst +++ b/doc/dev/tutorial/view.rst @@ -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 ` 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