*: Update additional documentation/comments 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 2026-08-17 15:49:30 -07:00 committed by James Valleroy
parent d128836d2f
commit 65ba2704a0
No known key found for this signature in database
GPG Key ID: 77C0C75E7B650808
23 changed files with 97 additions and 94 deletions

View File

@ -78,7 +78,7 @@ development environment inside a systemd-nspawn container.
1. To run unit and functional tests for an app:
```bash
host$ ./container run-tests --pytest-args -v --include-functional --splinter-headless plinth/modules/{app-name}
host$ ./container run-tests --pytest-args -v --include-functional --splinter-headless freedombox/modules/{app-name}
```
Drop the option `--splinter-headless` if you want to see the tests running
@ -420,11 +420,12 @@ The easiest way to start translating is with your browser, by using
Your changes will automatically get pushed to the code repository.
Alternatively, you can directly edit the `.po` file in your language directory
`Plinth/plinth/locale/` and create a pull request (see [CONTRIBUTING.md](CONTRIBUTING.md)).
In that case, consider introducing yourself on #freedombox IRC (irc.debian.org),
because some work may have been done already on the [Debian translators
discussion lists](https://www.debian.org/MailingLists/subscribe)
or the Weblate localization platform.
`freedombox/freedombox/locale/` and create a pull request (see
[CONTRIBUTING.md](CONTRIBUTING.md)). In that case, consider introducing yourself
on #freedombox IRC (irc.debian.org), because some work may have been done
already on the [Debian translators discussion
lists](https://www.debian.org/MailingLists/subscribe) or the Weblate
localization platform.
For more information on translations: https://wiki.debian.org/FreedomBox/Translate
@ -449,16 +450,16 @@ options. See pytest documentation for further filter options.
```bash
# Run tests in a directory
guest$ py.test-3 plinth/tests
guest$ py.test-3 freedombox/tests
# Run tests in a module
guest$ py.test-3 plinth/tests/test_actions.py
guest$ py.test-3 freedombox/tests/test_actions.py
# Run tests of one class in test module
guest$ py.test-3 plinth/tests/test_actions.py::TestActions
guest$ py.test-3 freedombox/tests/test_actions.py::TestActions
# Run one test in a class or module
guest$ py.test-3 plinth/tests/test_actions.py::TestActions::test_is_package_manager_busy
guest$ py.test-3 freedombox/tests/test_actions.py::TestActions::test_is_package_manager_busy
```
Some tests are skipped by default:
@ -489,13 +490,13 @@ guest$ sudo EXTENDED_TESTING=1 py.test-3
To run the coverage tool in the container/VM:
```bash
guest$ py.test-3 --cov=plinth
guest$ py.test-3 --cov=freedombox
```
To collect HTML report:
```bash
guest$ py.test-3 --cov=plinth --cov-report=html
guest$ py.test-3 --cov=freedombox --cov-report=html
```
Invoking this command generates a HTML report to the `htmlcov` directory.
@ -519,7 +520,7 @@ executed (red).
Inside the container run
```bash
guest$ cd /freedombox ; sudo plinth/tests/functional/install.sh
guest$ cd /freedombox ; sudo freedombox/tests/functional/install.sh
```
##### For running tests inside the VM
@ -565,13 +566,14 @@ on the guest.
#### Setup FreedomBox Service for tests
Via Plinth, create a new user as follows:
Via FreedomBox web interface, create a new user as follows:
* Username: tester
* Password: testingtesting
This step is optional if a fresh install of Plinth is being tested. Functional
tests will create the required user using FreedomBox's first boot process.
This step is optional if a fresh install of FreedomBox is being tested.
Functional tests will create the required user using FreedomBox's first boot
process.
#### Running Functional Tests
@ -620,7 +622,7 @@ In the VM or container, run the following command:
```
guest$ cd /freedombox
guest$ sudo make build install
guest$ plinth/tests/functional/enable-all-apps
guest$ freedombox/tests/functional/enable-all-apps
```
[back to index](#hacking)

View File

@ -30,7 +30,7 @@ FreedomBox [Manual](https://wiki.debian.org/FreedomBox/Manual/)'s
2. Run FreedomBox Service (Plinth):
```
$ sudo plinth
$ sudo systemctl start plinth.service
```
3. Access FreedomBox UI:

View File

@ -236,7 +236,7 @@ then
/freedombox/plinth/tests/functional/install.sh
fi
# Run the plinth server if functional tests are requested
# Wait for the server to start if functional tests are requested
if [[ "{pytest_command}" =~ "--include-functional" ]]
then
make -C /freedombox wait-while-first-setup

View File

@ -39,9 +39,9 @@
</If>
##
## Redirect traffic on home to /freedombox as part of turning the machine
## into FreedomBox server. Plinth then acts as a portal to reach all
## other services.
## Redirect traffic on home to /freedombox as part of turning the machine into
## FreedomBox server. FreedomBox then acts as a portal to reach all other
## services.
##
<IfFile !/etc/apache2/conf-enabled/freedombox-apache-homepage.conf>
RedirectMatch "^/$" "/freedombox"
@ -58,7 +58,7 @@
<Location /freedombox>
ProxyPass http://127.0.0.1:8000/freedombox
ProxyPreserveHost On
## Send the scheme from user's request to enable Plinth to redirect
## Send the scheme from user's request to enable FreedomBox to redirect
## URLs, set cookies, set absolute URLs (if any) properly.
RequestHeader set X-Forwarded-Proto 'https' env=HTTPS

View File

@ -1,20 +1,19 @@
# Apache configuration for the Plinth itself is shipped with proper
# name plinth.conf. However, due to the nature of the package, Plinth
# takes the responsibility of configuring various other services
# behind Apache. The upstream hence ships various Apache
# configuration files which are enabled and disabled when user
# requests.
# Apache configuration for the FreedomBox service itself is shipped with proper
# name freedombox.conf. However, due to the nature of the package, FreedomBox
# takes the responsibility of configuring various other services behind Apache.
# The upstream hence ships various Apache configuration files which are enabled
# and disabled when user requests.
freedombox binary: non-standard-apache2-configuration-name *
# Plinth depends on Apache2 and cannot work with just any web server. Instead of
# being a simple web application it is an administration console that configures
# web servers. At some point we would like to work with other web servers but
# that requires significant effort.
# FreedomBox depends on Apache2 and cannot work with just any web server.
# Instead of being a simple web application it is an administration console that
# configures web servers. At some point we would like to work with other web
# servers but that requires significant effort.
freedombox binary: web-application-works-only-with-apache
# Not documentation
freedombox: package-contains-documentation-outside-usr-share-doc [usr/share/plinth/static/jslicense.html]
freedombox: package-contains-documentation-outside-usr-share-doc [usr/lib/python3/dist-packages/plinth-*.dist-info/top_level.txt]
freedombox: package-contains-documentation-outside-usr-share-doc [usr/lib/python3/dist-packages/freedombox-*.dist-info/top_level.txt]
# This executable is meant to executed from systemd service file and is not
# meant for user. However, don't install to /usr/libexec and follow systemd

View File

@ -1,5 +1,5 @@
#
# Smoke test to check various basics on an installed version of Plinth. This
# Smoke test to check various basics on an installed version of FreedomBox. This
# checks that the following aspects are working okay:
# - Python runtime
# - Python library dependencies

View File

@ -53,14 +53,13 @@
data stays with the users.
</para>
<para>
Plinth is a web interface to administer the functions of the
FreedomBox. It is extensible and is made of modules. Each
module provides a simplified user interface to control the
underlying functionality of a specific application of
FreedomBox. As FreedomBox can act as a wireless router, it is
possible to configure networking from Plinth. Plinth allows
configuration of basic system parameters such as time zone,
hostname and automatic upgrade settings.
FreedomBox Service (Plinth) has a web interface to administer its
functions. It is extensible and is made of modules. Each module provides
a simplified user interface to control the underlying functionality of a
specific application of FreedomBox. As FreedomBox can act as a wireless
router, it is possible to configure networking. FreedomBox allows
configuration of basic system parameters such as time zone, hostname and
automatic upgrade settings.
</para>
</refsect1>
@ -71,9 +70,9 @@
<term><option>--server_dir SERVER_DIR</option></term>
<listitem>
<para>
This the URL fragment under which Plinth will provide its services.
Plinth is shipped with a default value of
<filename>/freedombox</filename>. This means that Plinth will be
This the URL fragment under which FreedomBox will provide its services.
FreedomBox is shipped with a default value of
<filename>/freedombox</filename>. This means that FreedomBox will be
available as http://localhost:8000/freedombox by default.
</para>
</listitem>
@ -86,8 +85,8 @@
from the current working directory. Enables extra debug messages,
enable Django debug mode for detailed error pages and turn off
Django security features. Monitor source files for changes and
restart Plinth on modifications. Die if there is an error during
module initialization.
restart FreedomBox Service on modifications. Die if there is an
error during module initialization.
</para>
</listitem>
</varlistentry>
@ -95,7 +94,7 @@
<term><option>--diagnose</option></term>
<listitem>
<para>
If provided, Plinth loads modules, performs initialization
If provided, FreedomBox loads modules, performs initialization
but does start the web server. Instead it runs diagnostic
tests on each module and exits.
</para>
@ -166,7 +165,7 @@
<refsect1>
<title>Configuration</title>
<para>
Plinth reads various configuration options from the files
FreedomBox Service reads various configuration options from the files
<filename>/usr/share/freedombox/freedombox.config</filename>,
<filename>/usr/share/freedombox/freedombox.config.d/*.config</filename>,
<filename>/etc/plinth/plinth.config</filename>,
@ -182,25 +181,25 @@
<title>Examples</title>
<example>
<title>Start Plinth with default options</title>
<title>Start FreedomBox Service with default options</title>
<synopsis>$ plinth</synopsis>
<para>
Run Plinth as guided by configuration file.
Run FreedomBox Service as guided by configuration file.
</para>
</example>
<example>
<title>Run Plinth with different URL prefix</title>
<title>Run FreedomBox Service with different URL prefix</title>
<synopsis>$ plinth --server_dir='/myurl'</synopsis>
<para>
Run Plinth with the '/myurl' prefix. Note that Apache forwards requests
to '/freedombox' by default, so /myurl is not accessible outside of your
FreedomBox without adapting the apache configuration.
Run FreedomBox with the '/myurl' prefix. Note that Apache forwards
requests to '/freedombox' by default, so /myurl is not accessible
outside of your FreedomBox without adapting the apache configuration.
</para>
</example>
<example>
<title>Run Plinth in development mode</title>
<title>Run FreedomBox Service in development mode</title>
<synopsis>$ plinth --develop</synopsis>
<para>
Run in development mode on the terminal. Enable auto-reloading and
@ -213,7 +212,7 @@
<title>Bugs</title>
<para>
See <ulink
url="https://salsa.debian.org/freedombox-team/freedombox/issues">Plinth
url="https://salsa.debian.org/freedombox-team/freedombox/issues">FreedomBox
issue tracker</ulink> for a full list of known issues and TODO items.
</para>
</refsect1>
@ -222,7 +221,7 @@
<title>Author</title>
<para>
<author>
<firstname>Plinth Developers</firstname>
<firstname>FreedomBox Developers</firstname>
<contrib>Original author</contrib>
</author>
</para>

View File

@ -1192,12 +1192,12 @@ from="## BEGIN_INCLUDE", to="## END_INCLUDE")>>')
>>> parse_wiki('{{{#!wiki caution\\n\\nOnce some other app is set as the \
home page, you can only navigate to the !FreedomBox Service (Plinth) by \
typing https://myfreedombox.rocks/freedombox/ into the browser. <<BR>>\\n\
''/freedombox'' can also be used as an alias to ''/plinth''\\n}}}')
''/plinth'' can also be used as an alias to ''/freedombox''\\n}}}')
[Admonition('caution', [Paragraph([PlainText('Once some other app is set \
as the home page, you can only navigate to the FreedomBox Service (Plinth) by \
typing '), Url('https://myfreedombox.rocks/freedombox/'), PlainText(' into the \
browser. ')]), Paragraph([PlainText('/freedombox can also be used as an alias \
to /plinth ')])])]
browser. ')]), Paragraph([PlainText('/plinth can also be used as an alias \
to /freedombox ')])])]
>>> parse_wiki('{{{\\nmulti-line\\n\
preformatted text (source code)\\n}}}''')
@ -1773,8 +1773,8 @@ Code</ulink>'
'<ulink url="https://bugs.debian.org/1234#">Bug</ulink>'
>>> generate_inner_docbook([Link('DebianPkg:freedombox', \
[PlainText('Plinth')])])
'<ulink url="https://packages.debian.org/freedombox#">Plinth</ulink>'
[PlainText('FreedomBox')])])
'<ulink url="https://packages.debian.org/freedombox#">FreedomBox</ulink>'
>>> generate_inner_docbook([Link('AliothList:freedombox-discuss', \
[PlainText('Discuss')])])

View File

@ -29,7 +29,7 @@ def parse_arguments():
help='web server path under which to serve')
parser.add_argument(
'--develop', action='store_true', default=None,
help=('run Plinth *insecurely* from current folder; '
help=('run FreedomBox Service *insecurely* from current folder; '
'enable auto-reloading and debugging options'))
parser.add_argument('--setup', default=False, nargs='*',
help='run setup tasks on all essential apps and exit')

View File

@ -18,9 +18,9 @@ from . import actions
logger = logging.getLogger(__name__)
# Flag on disk to indicate if freedombox package was held by
# plinth. This is a backup in case the process is interrupted and hold
# is not released.
# Flag on disk to indicate if freedombox package was held by FreedomBox
# Service. This is a backup in case the process is interrupted and hold is not
# released.
apt_hold_flag = pathlib.Path('/var/lib/freedombox/package-held')

View File

@ -130,7 +130,7 @@ class App:
def info(self):
"""Return the information component of the app.
It is mandatory to have one :class:`~plinth.app.Info` component in
It is mandatory to have one :class:`~freedombox.app.Info` component in
every app to provide basic information about the app. Trying to access
this property without having the Info component will result in a
KeyError exception being raised. The lookup for the Info component is
@ -230,7 +230,7 @@ class App:
"""Run diagnostics and return results.
Return value must be a list of results. Each result is a
:class:`~plinth.diagnostic_check.DiagnosticCheck` with a
:class:`~freedombox.diagnostic_check.DiagnosticCheck` with a
unique check_id, a user visible description of the test, the result,
test parameters, and the component ID. The test result is a string
enumeration from 'failed', 'passed', 'error', 'warning' and 'not_done'.
@ -380,7 +380,7 @@ class Component:
"""Run diagnostics and return results.
Return value must be a list of results. Each result is a
:class:`~plinth.diagnostic_check.DiagnosticCheck` with a
:class:`~freedombox.diagnostic_check.DiagnosticCheck` with a
unique check_id, a user visible description of the test, the result,
test parameters, and the component ID. The test result is a string
enumeration from 'failed', 'passed', 'error', 'warning' and 'not_done'.
@ -533,7 +533,7 @@ class Info(FollowerComponent):
'clients' is the list of applications that can be used with the
services provided by this app. This is used to suggest installation of
compatible clients on desktop, web and mobile. This is a list of
dictionaries who structure is documented in plinth.clients.
dictionaries who structure is documented in freedombox.clients.
'donation_url' is a link to a webpage that describes how to
donate to the upstream project.

View File

@ -22,7 +22,7 @@ server_dir = '/freedombox'
host = '127.0.0.1'
port = 8000
# Enable the following only if Plinth is behind a proxy server. The
# Enable the following only if FreedomBox is behind a proxy server. The
# proxy server should properly clean and the following HTTP headers:
# X-Forwarded-For
# X-Forwarded-Host

View File

@ -121,7 +121,7 @@ class Container(app.LeaderComponent, log.LogEmitter):
def diagnose(self) -> list[DiagnosticCheck]:
"""Check if the container is running..
See :py:meth:`plinth.app.Component.diagnose`.
See :py:meth:`freedombox.app.Component.diagnose`.
"""
results = []
results.append(self._diagnose_unit_is_running())

View File

@ -111,7 +111,7 @@ class Daemon(app.LeaderComponent, log.LogEmitter):
def diagnose(self) -> list[DiagnosticCheck]:
"""Check if the daemon is running and listening on expected ports.
See :py:meth:`plinth.app.Component.diagnose`.
See :py:meth:`freedombox.app.Component.diagnose`.
"""
results = []

View File

@ -27,12 +27,13 @@ class Menu(app.FollowerComponent):
name of an SVG icon from the static/theme/icons directory. In this
case, the icon name starts with the string 'fa-' (a tribute to the
fork-awesome project). Alternatively, the icon can also be a file under
the directory plinth/modules/<app>/static/icons/, provided without an
extension. SVG icons are preferred. Currently, both PNG and SVG icons
with the same name are used. For example, if the value of icon is
the directory freedombox/modules/<app>/static/icons/, provided without
an extension. SVG icons are preferred. Currently, both PNG and SVG
icons with the same name are used. For example, if the value of icon is
'myicon' and app_id in App class is 'myapp', then two icons files
plinth/modules/myapp/static/icons/myicon.svg and
plinth/modules/myapp/static/icons/myicon.png are used in the interface.
freedombox/modules/myapp/static/icons/myicon.svg and
freedombox/modules/myapp/static/icons/myicon.png are used in the
interface.
tags is a list of tags that describe the app. Tags help users to find
similar apps or alternatives and discover use cases.

View File

@ -66,7 +66,7 @@ class Webserver(app.LeaderComponent):
def diagnose(self) -> list[DiagnosticCheck]:
"""Check if the web path is accessible by clients.
See :py:meth:`plinth.app.Component.diagnose`.
See :py:meth:`freedombox.app.Component.diagnose`.
"""
results = []
for url in self.urls:
@ -175,7 +175,7 @@ class WebserverRoot(app.FollowerComponent):
def diagnose(self) -> list[DiagnosticCheck]:
"""Check if the site root path is accessible by clients.
See :py:meth:`plinth.app.Component.diagnose`.
See :py:meth:`freedombox.app.Component.diagnose`.
"""
results = []
domain = self.domain_get()

View File

@ -1,6 +1,6 @@
# SPDX-License-Identifier: AGPL-3.0-or-later
"""
URLs for the plinth api for android app.
URLs for the FreedomBox API for Android app.
"""
from django.urls import re_path

View File

@ -387,7 +387,7 @@ def get_archive_apps(
def _get_apps_of_manifest(manifest):
"""Get apps of a manifest.
Supports both dict format as well as list format of plinth <=0.42
Supports both dict format as well as list format of freedombox <=0.42
"""
if isinstance(manifest, list):

View File

@ -177,7 +177,7 @@ def _backup_schedule_set(browser, enable, daily, weekly, monthly, run_at,
def _download_file_logged_in(browser, url, suffix=''):
"""Download a file from Plinth, pretend being logged in via cookies"""
"""Download a file from FreedomBox, pretend being logged in via cookies."""
if not url.startswith('http'):
current_url = urllib.parse.urlparse(browser.url)
url = '%s://%s%s' % (current_url.scheme, current_url.netloc, url)

View File

@ -14,9 +14,9 @@ clients = [{
}]
# cockpit.conf need not be backed up because add/remove domain signals are
# triggered on every Plinth domain change (and cockpit application install) and
# will set the value of allowed domains correctly. This is the only key the is
# customized in cockpit.conf.
# triggered on every FreedomBox domain change (and cockpit application install)
# and will set the value of allowed domains correctly. This is the only key the
# is customized in cockpit.conf.
backup: dict = {}
tags = [

View File

@ -2,9 +2,10 @@
"""URLs for the OpenID Connect module.
All the '/freedombox/o' URLs are implemented in this module by including them
from django-oauth-toolkit. However, they are included in plinth/urls.py instead
of here because FreedomBox module loading logic automatically namespaces the
URL names. This causes problems when metadata view tries to resolve URLs.
from django-oauth-toolkit. However, they are included in freedombox/urls.py
instead of here because FreedomBox module loading logic automatically
namespaces the URL names. This causes problems when metadata view tries to
resolve URLs.
/.well-known/openid-configuration is proxied to
/freedombox/o/.well-known/openid-configuration by Apache2. Similarly,

View File

@ -1,6 +1,6 @@
# SPDX-License-Identifier: AGPL-3.0-or-later
"""
pytest configuration for all tests in the plinth/tests/ directory.
pytest configuration for all tests in the freedombox/tests/ directory.
"""
import pathlib

View File

@ -5,6 +5,7 @@ Dummy file to help pytest-django path detection.
pytest-django searches for a folder with manage.py and treats that as parent
directory for Django project. This folder is then added to Python path managed
in sys.path. This allows the Django setting module to be discovered as
plinth.tests.data.django_test_settings. pytest can then be invoked simply as
'py.test-3' instead of 'python3 -m pytest'.
freedombox.tests.data.django_test_settings. pytest can then be invoked simply
as 'py.test-3' instead of 'python3 -m pytest'.
"""