From 213e01abcdff2da6c7a366d8ccbc407b010ab82d Mon Sep 17 00:00:00 2001 From: Carlos Henrique Lima Melara Date: Tue, 13 Apr 2021 12:14:14 -0300 Subject: [PATCH] doc: Add filename to code snippets in tutorial [sunil: Add caption for another file too] Signed-off-by: Sunil Mohan Adapa Reviewed-by: Sunil Mohan Adapa --- doc/dev/tutorial/components.rst | 11 +++++++++++ doc/dev/tutorial/customizing.rst | 5 +++++ doc/dev/tutorial/other.rst | 3 +++ doc/dev/tutorial/setup.rst | 1 + doc/dev/tutorial/skeleton.rst | 7 ++++++- doc/dev/tutorial/view.rst | 3 +++ 6 files changed, 29 insertions(+), 1 deletion(-) diff --git a/doc/dev/tutorial/components.rst b/doc/dev/tutorial/components.rst index 5a13a5bf7..a3900fb16 100644 --- a/doc/dev/tutorial/components.rst +++ b/doc/dev/tutorial/components.rst @@ -16,6 +16,7 @@ We need to provide some basic information about the application for the app to function normally. .. code-block:: python3 + :caption: ``__init__.py`` from plinth import app as app_module @@ -60,6 +61,7 @@ need to list them and present them. Let's add this information to ``manifest.py``. .. code-block:: python3 + :caption: ``manifest.py`` clients = [{ 'name': _('Transmission'), @@ -84,6 +86,7 @@ concerns are automatically handled by the framework if a our app's class. .. code-block:: python3 + :caption: ``__init__.py`` from plinth.daemon import Daemon @@ -120,6 +123,7 @@ these concerns are automatically handled by the framework if a app. Let us do that in our app's class. .. code-block:: python3 + :caption: ``__init__.py`` from plinth.modules.apache.components import Webserver @@ -143,6 +147,7 @@ This information is used to check if the URLs are accessible as expected when the user requests diagnostic tests on the app. .. code-block:: apache + :caption: ``data/etc/apache2/conf-available/transmission-freedombox.conf`` ## On all sites, provide Transmission on a default path: /transmission @@ -166,6 +171,7 @@ available over Internet. Create the initialization. .. code-block:: python3 + :caption: ``__init__.py`` from plinth.modules.firewall.components import Firewall @@ -196,6 +202,7 @@ and we simply need to declare and use. First we need to register a user group with the FreedomBox framework in ``__init.py__``. .. code-block:: python3 + :caption: ``__init__.py`` from plinth.modules.users.components import UsersAndGroups @@ -216,6 +223,7 @@ group (and, of course, admin users) should be allowed to access our app. In the file ``tranmission-freedombox.conf``, add the following. .. code-block:: apache + :caption: ``data/etc/apache2/conf-available/transmission-freedombox.conf`` ... @@ -236,6 +244,7 @@ when they visit FreedomBox. To provide this shortcut, a :class:`~plinth.frontpage.Shortcut` component can added to the app. .. code-block:: python3 + :caption: ``__init__.py`` from plinth import frontpage @@ -277,6 +286,7 @@ initialization. In ``__init__.py``, add: .. code-block:: python3 + :caption: ``__init__.py`` from plinth.modules.backups.components import BackupRestore @@ -295,6 +305,7 @@ In ``__init__.py``, add: In ``manifest.py``, add: .. code-block:: python3 + :caption: ``manifest.py`` backup = { 'data': { diff --git a/doc/dev/tutorial/customizing.rst b/doc/dev/tutorial/customizing.rst index 6b4c24f6f..e113f4e69 100644 --- a/doc/dev/tutorial/customizing.rst +++ b/doc/dev/tutorial/customizing.rst @@ -11,6 +11,7 @@ file is provided by the framework. In some cases, we will need to customize this template. Let us create a custom template file in ``transmission.html``. .. code-block:: django + :caption: ``templates/transmission.html`` {% extends "app.html" %} @@ -48,6 +49,7 @@ To start using our custom template, we need to pass this to our view. In ``views.py``, add the following line: .. code-block:: python3 + :caption: ``views.py`` class TransmissionAppView(AppView): ... @@ -60,6 +62,7 @@ Our app needs some configuration. So, we need to write a configuration form to provide options to the user. Add the following to ``forms.py``. .. code-block:: python3 + :caption: ``forms.py`` from django import forms @@ -95,6 +98,7 @@ The view we have created needs to display the form and process the form after the user submits it. Let us implement that in ``views.py``. .. code-block:: python3 + :caption: ``views.py`` from django.contrib import messages @@ -157,6 +161,7 @@ enable and disable the web configuration. We will do this by creating a file ``actions/transmission``. .. code-block:: python3 + :caption: ``actions/transmission`` import argparse import json diff --git a/doc/dev/tutorial/other.rst b/doc/dev/tutorial/other.rst index 69ea99595..135678848 100644 --- a/doc/dev/tutorial/other.rst +++ b/doc/dev/tutorial/other.rst @@ -21,6 +21,7 @@ itself is a two-tuple containing the display name of the test followed by the result as ``passed``, ``failed`` or ``error``. .. code-block:: python3 + :caption: ``views.py`` class TransmissionAppView(views.AppView): ... @@ -47,6 +48,7 @@ system logs. Doing this in FreedomBox is just like doing this any other Python application. .. code-block:: python3 + :caption: ``views.py`` import logging @@ -75,6 +77,7 @@ requires marking the user visible messages for translation. FreedomBox apps use the Django's localization methods to make that happen. .. code-block:: python3 + :caption: ``__init__.py`` from django.utils.translation import ugettext_lazy as _ diff --git a/doc/dev/tutorial/setup.rst b/doc/dev/tutorial/setup.rst index 5a3f111b7..a7fddc0ac 100644 --- a/doc/dev/tutorial/setup.rst +++ b/doc/dev/tutorial/setup.rst @@ -14,6 +14,7 @@ Debian packages required in the ``setup()`` method that is called during installation: .. code-block:: python3 + :caption: ``__init__.py`` managed_packages = ['transmission-daemon'] diff --git a/doc/dev/tutorial/skeleton.rst b/doc/dev/tutorial/skeleton.rst index 729f87348..5669df0d8 100644 --- a/doc/dev/tutorial/skeleton.rst +++ b/doc/dev/tutorial/skeleton.rst @@ -52,7 +52,10 @@ 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/etc/plinth/modules-enabled/``. Let us create -this file ``transmission``:: +this file ``transmission``: + +.. code-block:: text + :caption: ``plinth/modules/transmission/data/etc/plinth/modules-enabled/transmission`` plinth.modules.transmission @@ -71,6 +74,7 @@ In the FreedomBox framework, each app must be a class derived from the class later. .. code-block:: python3 + :caption: ``__init__.py`` from plinth import app as app_module @@ -89,6 +93,7 @@ itself by calling the ``init()`` method if there is such a method available as ``.init()``. The app class must be instantiated here. .. code-block:: python3 + :caption: ``__init__.py`` app = None diff --git a/doc/dev/tutorial/view.rst b/doc/dev/tutorial/view.rst index 181d442bb..4fd60e06a 100644 --- a/doc/dev/tutorial/view.rst +++ b/doc/dev/tutorial/view.rst @@ -11,6 +11,7 @@ user visits this URL, a view is executed and a page is displayed. In ``urls.py`` write the following: .. code-block:: python3 + :caption: ``urls.py`` from django.conf.urls import url @@ -33,6 +34,7 @@ a link in FreedomBox web interface. Let us add a link in the apps list. In ``__init__.py`` add the following: .. code-block:: python3 + :caption: ``__init__.py`` from plinth.menu import main_menu @@ -83,6 +85,7 @@ section of the web interface that points to our view. We now need to create a 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