nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-05-27 10:44:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: dev: Remove short description and add tags to all components

Browse Source 
Tests:

- Build developer documentation and ensure that there are no errors during build
and all changes are reflected.

Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org>
Reviewed-by: Joseph Nuthalapati <njoseph@riseup.net>
This commit is contained in:
Sunil Mohan Adapa 2024-12-30 21:44:41 -08:00 committed by Joseph Nuthalapati
parent 89bce7a344
commit f2d99106af
No known key found for this signature in database
GPG Key ID: 5398F00A2FA43C35
3 changed files with 44 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -30,23 +30,21 @@ function normally.
def __init__(self): def __init__(self):
... ...
info = app_module.Info(app_id=self.app_id, version=1, info = app_module.Info(
name=_('Transmission'), app_id=self.app_id, version=1, name=_('Transmission'),
icon_filename='transmission', icon_filename='transmission', description=_description,
short_description=_('BitTorrent Web Client'), manual_page='Transmission', clients=manifest.clients,
description=description, donation_url='https://transmissionbt.com/donate/',
manual_page='Transmission', tags=manifest.tags)
clients=manifest.clients,
donation_url='https://transmissionbt.com/donate/')
self.add(info) self.add(info)
The first argument is app_id that is same as the ID for the app. The version is The first argument is app_id that is same as the ID for the app. The version is
the version number for this app that must be incremented whenever setup() method the version number for this app that must be incremented whenever setup() method
needs to be called again. name, icon_filename, short_description, description, needs to be called again. name, icon_filename, description, manual_page,
manual_page and clients provide information that is shown on the app's main clients, and tags provide information that is shown on the app's main page. The
page. The donation_url encourages our users to contribute to upstream projects donation_url encourages our users to contribute to upstream projects in order
in order ensure their long term sustainability. More information about the ensure their long term sustainability. More information about the parameters is
parameters is available in :class:`~plinth.app.Info` class documentation. available in :class:`~plinth.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
@ -322,22 +320,24 @@ when they visit FreedomBox. To provide this shortcut, a
def __init__(self): def __init__(self):
... ...
shortcut = frontpage.Shortcut( shortcut = frontpage.Shortcut('shortcut-transmission', info.name,
'shortcut-transmission', name, short_description=short_description, icon=info.icon_filename,
icon='transmission', url='/transmission', clients=clients, url='/transmission',
login_required=True, allowed_groups=[group[0]]) clients=info.clients, tags=info.tags,
login_required=True,
allowed_groups=list(groups))
self.add(shortcut) self.add(shortcut)
The first parameter, as usual, is a unique ID. The next three parameters are The first parameter, as usual, is a unique ID. The next two parameters are basic
basic information about the app similar to the menu item. The URL parameter information about the app similar to the menu item. The URL parameter specifies
specifies the URL that the user should be directed to when the shortcut is the URL that the user should be directed to when the shortcut is clicked. This
clicked. This is the web interface provided by our app. The next parameter is the web interface provided by our app. The next parameter provides a list of
provides a list of clients. This is useful for the FreedomBox mobile app when clients. This is useful for the FreedomBox mobile app when the information is
the information is used to suggest installing mobile apps. This is described in used to suggest installing mobile apps. This is described in a later section of
a later section of this tutorial. The next parameter specifies whether anonymous this tutorial. The next parameter specifies the list of tags to show on the
users who are not logged into FreedomBox should be shown this shortcut. The shortcut. The next parameter specifies whether anonymous users who are not
final parameter further restricts to which group of users this shortcut must be logged into FreedomBox should be shown this shortcut. The final parameter
shown. further restricts to which group of users this shortcut must be shown.
Adding backup/restore functionality Adding backup/restore functionality
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

@ -89,22 +89,23 @@ the Django's localization methods to make that happen.
info = app_module.Info(... info = app_module.Info(...
name=_('Transmission'), name=_('Transmission'),
description=[_('Transmission is a...'),
_('BitTorrent is a peer-to-peer...')],
... ...
short_description=_('BitTorrent Web Client'), tags=[_('File sharing'), _('BitTorrent'), ...])
...) ...)
Notice that the app's name, description, etc. are wrapped in the ``_()`` method Notice that the app's name, description, tags, etc. are wrapped in the ``_()``
call. This needs to be done for the rest of our app. We use the method calls. This needs to be done for the rest of our app. We use the
:obj:`~django.utils.translation.gettext_lazy` in some cases and we use the :obj:`~django.utils.translation.gettext_lazy` in some cases and we use the
regular :obj:`~django.utils.translation.gettext` in other cases. This is regular :obj:`~django.utils.translation.gettext` in other cases. This is because
because in the second case the :obj:`~django.utils.translation.gettext` lookup in the second case the :obj:`~django.utils.translation.gettext` lookup is made
is made once and reused for every user looking at the interface. These users may once and reused for every user looking at the interface. These users may each
each have a different language set for their interface. Lookup made for one have a different language set for their interface. Lookup made for one language
language for a user should not be used for other users. The ``_lazy`` methods for a user should not be used for other users. The ``_lazy`` methods provided by
provided by Django makes sure that the return value is an object that will Django makes sure that the return value is an object that will actually be
actually be converted to string at the final moment when the string is being converted to string at the final moment when the string is being displayed. In
displayed. In the first case, the lookup is made and string is returned the first case, the lookup is made and string is returned immediately.
immediately.
All of this is the usual way internationalization is done in Django. See All of this is the usual way internationalization is done in Django. See
:doc:`Internationalization and localization <django:topics/i18n/index>` :doc:`Internationalization and localization <django:topics/i18n/index>`

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

@ -45,7 +45,7 @@ a link in FreedomBox web interface. Let us add a link in the apps list. In
... ...
menu_item = menu.Menu('menu-transmission', 'Transmission', menu_item = menu.Menu('menu-transmission', 'Transmission',
'BitTorrrent Web Client', 'transmission', 'transmission', info.tags,
'transmission:index', parent_url_name='apps') 'transmission:index', parent_url_name='apps')
self.add(menu_item) self.add(menu_item)
@ -61,12 +61,12 @@ menu item we want to present.
* The second parameter is the display name to use for our menu item which * The second parameter is the display name to use for our menu item which
happens to be the name of the app as well. happens to be the name of the app as well.
* The third parameter is a short description for the menu item. * The third parameter is the name of the icon to use when showing the menu
* The fourth 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. ``plinth/modules/transmission/static/icons/`` directory.
* The fourth parameter is the list of tags to show on the menu item.
* The fifth parameter is the URL that the user should be directed to when the * The fifth parameter is the URL that the user should be directed to when the
menu item is clicked. This is a Django URL name and we have already created a menu item is clicked. This is a Django URL name and we have already created a
URL with this name. Note that when including our app's URLs, FreedomBox will URL with this name. Note that when including our app's URLs, FreedomBox will