Update comments in actions; remove workbench folder in rate

docs/conf.py

@@ -211,7 +211,6 @@ class DhlistDirective(Directive):
                     yield obj
 
     def run(self):
-        env = self.state.document.settings.env
         module = importlib.import_module(self.options['module'])
         things = tuple(self._import(module))
 

ereuse_devicehub/resources/action/models.py

@@ -645,17 +645,13 @@ class BenchmarkGraphicCard(BenchmarkWithRate):
 
 
 class Test(JoinedWithOneDeviceMixin, ActionWithOneDevice):
-    """The act of testing the physical condition of a device and its
+    """The act of documenting the functionality of a device, as
-    components.
+    for the R2 Standard (R2 Provision 6 pag.19).
 
-    Ref in R2 Provision 6 pag.19:
+    :attr:`.severity` in :class:`Action` defines a passing or failing
-    Records of test results are imperative to documenting
+    test, and
-    the functionality of each device.
+    :attr:`ereuse_devicehub.resources.device.models.Device.working`
-    Pass or fail results for each test in the process must be recorded
+    in Device gets all tests with warnings or errors for a device.
-    either manually or through software automation.
-
-    Testing errors and warnings are easily taken in
-    :attr:`ereuse_devicehub.resources.device.models.Device.working`.
     """
 
     @declared_attr
@@ -681,23 +677,13 @@ class TestMixin:
 
 
 class MeasureBattery(TestMixin, Test):
-    """
+    """A sample of the status of the battery.
-    A sample of the status of the battery.
+
     Ref in R2 Provision 6 pag.22 Example:
     Length of charge; Expected results: Minimum 40 minutes.
 
     Operative Systems keep a record of several aspects of a battery.
     This is a sample of those.
-
-    :class: 'Severtity'
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
-
     """
     size = db.Column(db.Integer, nullable=False)
     size.comment = """Maximum battery capacity, in mAh."""
@@ -714,8 +700,7 @@ class MeasureBattery(TestMixin, Test):
 
 
 class TestDataStorage(TestMixin, Test):
-    """
+    """The act of testing the data storage.
-    The act of testing the data storage.
 
     Testing is done using the `S.M.A.R.T self test
     <https://en.wikipedia.org/wiki/S.M.A.R.T.#Self-tests>`_. Note
@@ -725,15 +710,11 @@ class TestDataStorage(TestMixin, Test):
     The test takes to other SMART values indicators of the overall health
     of the data storage.
 
-    :class: 'Severtity'
+    Failing and warning conditions are as follows:
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
 
+    * :attr:`Severity.Error`: if the SMART test failed.
+    * :attr:`Severity.Warning`: if there is a significant chance for
+      the data storage to fail in the following year.
     """
     length = Column(DBEnum(TestDataStorageLength), nullable=False)  # todo from type
     status = Column(Unicode(), check_lower('status'), nullable=False)
@@ -783,8 +764,7 @@ class TestDataStorage(TestMixin, Test):
 
 class StressTest(TestMixin, Test):
     """The act of stressing (putting to the maximum capacity)
-    a device for an amount of minutes. If the device is not in great
+    a device for an amount of minutes.
-    condition won't probably survive such test.
     """
     elapsed = Column(Interval, nullable=False)
 
@@ -800,20 +780,7 @@ class StressTest(TestMixin, Test):
 
 
 class TestAudio(TestMixin, Test):
-    """
+    """The act of checking the audio aspects of the device."""
-    Test to check audio device aspects, focus on speaker sounds correctly
-    and microphone record sounds good
-
-    :class: 'Severtity'
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
-
-    """
     _speaker = Column('speaker', Boolean)
     _speaker.comment = """Whether the speaker works as expected."""
     _microphone = Column('microphone', Boolean)
@@ -844,82 +811,68 @@ class TestAudio(TestMixin, Test):
 
 
 class TestConnectivity(TestMixin, Test):
-    """
+    """The act of testing the connectivity of the device.
-    Tests that the device can connect both physically and wirelessly.
 
     A failing test means that at least one connection of the device
     is not working well. A comment should get into more detail.
-
-    :class: 'Severtity'
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
-
     """
 
 
 class TestCamera(TestMixin, Test):
-    """
+    """Tests the working conditions of the camera of the device,
-    Tests the working conditions of the camera of the device,
     specially when taking pictures or recording video.
-    Fail when camera can't take pictures.
+
+    Failing and warning conditions are as follows:
+
+    * :attr:`Severity.Error`: if the camera cannot turn on or
+      has significant visual problems.
+    * :attr:`Severity.Warning`: if there are small visual problems
+      with the camera (like dust) that it still allows it to be used.
     """
 
 
 class TestKeyboard(TestMixin, Test):
-    """
+    """Whether the keyboard works correctly.
-    Whether the keyboard works correctly.
 
-    Ref in R2 Provision 6 pag.22 example:
+    Failing and warning conditions are as follows:
-    PASS when each key produces character on the screen
+
+    * :attr:`Severity.Error`: if at least one key does not produce
+      a character on screen. This follows R2 Provision 6 pag.22.
     """
 
 
 class TestTrackpad(TestMixin, Test):
-    """
+    """Whether the trackpad works correctly.
-    Whether the trackpad works correctly.
 
-    Ref in R2 Provision 6 pag.22 example:
+     Failing and warning conditions are as follows:
-    PASS when cursor moves on screen
+
+    * :attr:`Severity.Error`: if the cursor does not move on screen.
+      This follows R2 Provision 6 pag.22.
     """
 
 
-class TestScreenHinge(TestMixin, Test):
+class TestDisplayHinge(TestMixin, Test):
-    """
+    """Whether display hinge works correctly.
-    Whether screen hinge works correctly.
 
-    Laptop Test Ref in R2 Provision 6 pag.22 example:
+    Failing and warning conditions are as follows:
-    PASS when laptop screen stays open/closed at desired angles
+
+    * :attr:`Severity.Error`: if the laptop does not stay open
+      or closed at desired angles. From R2 Provision 6 pag.22.
     """
 
 
 class TestPowerAdapter(TestMixin, Test):
-    """
+    """Whether power adapter charge battery device without problems.
-    Whether power adapter charge battery device without problems.
 
-    Laptop Test Ref in R2 Provision 6 pag.22 example:
+    Failing and warning conditions are as follows:
-    PASS when plug power adapter into laptop and charges the battery.
+
+    * :attr:`Severity.Error`: if the laptop does not charge battery.
+      This follows R2 Provision 6 pag.22.
     """
 
 
 class TestBios(TestMixin, Test):
-    """
+    """Tests the working condition and grades the usability of the BIOS."""
-    Tests the working condition and grades the usability of the BIOS.
-
-    :class: 'Severtity'
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
-
-    """
     beeps_power_on = Column(Boolean)
     beeps_power_on.comment = """Whether there are no beeps or error
     codes when booting up.
@@ -935,25 +888,12 @@ class TestBios(TestMixin, Test):
 
 
 class VisualTest(TestMixin, Test):
-    """
+    """The act of visually inspecting the appearance and functionality
-    The act of visually inspecting the appearance and functionality
     of the device.
 
     Reference R2 provision 6 Templates Ready for Resale Checklist (Desktop)
     https://sustainableelectronics.org/sites/default/files/6.c.2%20Desktop%20R2-Ready%20for%20Resale%20Checklist.docx
     Physical condition grade
-
-
-    :class: 'Severtity'
-        Info/Pass(0):
-
-        Notice(1):
-
-        Warning(2):
-
-        Error/Fail(3):
-
-
     """
     appearance_range = Column(DBEnum(AppearanceRange), nullable=False)
     appearance_range.comment = AppearanceRange.__doc__
@@ -970,13 +910,11 @@ class VisualTest(TestMixin, Test):
 
 
 class Rate(JoinedWithOneDeviceMixin, ActionWithOneDevice):
-    """
+    """The act of computing a rate based on different categories:
-    The act of computing a rate based on different categories:
-
-    • Functionality (F). Tests, the act of testing usage condition of a device
-    • Appearance (A). Visual evaluation, surface deterioration.
-    • Performance (Q). Components characteristics and components benchmarks.
 
+    * Functionality (F). Tests, the act of testing usage condition of a device
+    * Appearance (A). Visual evaluation, surface deterioration.
+    * Performance (Q). Components characteristics and components benchmarks.
     """
     # todo jn: explain in each comment what the rate considers.
     N = 2
@@ -1128,7 +1066,7 @@ class RateComputer(RateMixin, Rate):
         """
         The act of compute general computer rate
         """
-        from ereuse_devicehub.resources.action.rate.workbench.v1_0 import rate_algorithm
+        from ereuse_devicehub.resources.action.rate.v1_0 import rate_algorithm
         rate = rate_algorithm.compute(device)
         price = None
         with suppress(InvalidRangeForPrice):  # We will have exception if range == VERY_LOW

ereuse_devicehub/resources/action/rate/v1_0.py

@@ -12,54 +12,29 @@ from ereuse_devicehub.resources.device.models import Computer, DataStorage, Proc
 class RateAlgorithm(BaseRate):
     """The algorithm that generates the Rate v1.0.
 
-    Rate v1.0 is mainly based on 3 components (Processor, RAM and Data Storage)
+    Rate v1.0 rates only computers, counting their processor, ram,
-    and 2 visual grades (one for appearance aspects and other for functionality aspects).
+    data storage, appearance, and functionality. This rate is only
+    triggered by a Snapshot from Workbench that has a VisualTest.
+    The algorithm is as follows:
 
-    From components we take into account their main characteristics and
+    1. Specialized subclasses of :class:`BaseRate` compute a rating
-    also some tests and benchmarks. In particular:
+       for each component. To perform this, each class normalizes first
+       the characteristics and benchmarks of the components between
+       0 and 1, and then they merge the values to a resulting score.
+       The classes are:
 
-    * Processor:
+       * :class:`ProcessorRate`, using cores, speed, and ``BenchmarkProcessor``.
-        - Cores
+       * :class:`RamRate`, using the total of RAM size and speed.
-        - Speed
+       * :class:`DataStorageRate`, using the total of disk capacity,
-        - Benchmark processor
+         and ``BenchmarkDataStorage``.
-
+    2. Merge the components individual rates into a single rate for
-    * RAM:
+       all components, using a weighted harmonic mean of
-        - Size
+       50% for the processor rating, 20% for the data storage rating,
-        - Speed
+       and 30% for the RAM rating.
-
+    3. Merge the rate for the components with the appearance and
-    * Data Storage:
+       functionality from :class:`VisualTest`. ``Final Rate =
-        - Size
+       Components Rate + Functionality Rate + Appearance Rate``. The
-        - Benchmark data storage (Read and write speed)
+       value is between 0 and 4.7, included.
-
-    Step by step to compute Rate v1.0:
-
-    1. Normalization the components characteristics.
-        Normalized the characteristics of the components between 0 and 1.
-        with xMin and xMax and standardize the values applying
-        the following formula:
-
-        **Normalization characteristic value = (x −xMin)/(xMax −xMin)**
-
-    2. Merge the characteristics of every component in one score for component.
-
-
-    3. Merge the components individual rates into a single components rate.
-        We calculate this rate using the weighted harmonic mean.
-        We establish all the components weights, 50% for processor,
-        20% for data storage, 30% for RAM.
-        The result is a unique performance score (components rate).
-
-    4. Grouping all categories aspects sum all in unique final rate.
-        To get Functionality and Appearance Rates values, only directly
-        related a value for each grade.
-
-    **Final Rate = Components Rate + Functionality Rate + Appearance Rate**
-
-    Final Rate are ranged from 0 to 4.7.
-
-    Do not call directly this class, but use
-    :meth:`ereuse_devicehub.resources.action.models.RateComputer.compute`,
-    which then calls this.
     """
 
     @unique
@@ -91,6 +66,10 @@ class RateAlgorithm(BaseRate):
         """Generates a new
         :class:`ereuse_devicehub.resources.action.models.RateComputer`
         for the passed-in device.
+
+        Do not call directly this class, but use
+        :meth:`ereuse_devicehub.resources.action.models.RateComputer.compute`,
+        which then calls this.
         """
         assert isinstance(device, Computer), 'Can only rate computers'
 

ereuse_devicehub/resources/action/views.py

@@ -9,7 +9,7 @@ from teal.resource import View
 
 from ereuse_devicehub.db import db
 from ereuse_devicehub.resources.action.models import Action, RateComputer, Snapshot, VisualTest
-from ereuse_devicehub.resources.action.rate.workbench.v1_0 import CannotRate
+from ereuse_devicehub.resources.action.rate.v1_0 import CannotRate
 from ereuse_devicehub.resources.device.models import Component, Computer
 from ereuse_devicehub.resources.enums import SnapshotSoftware
 

tests/test_rate_workbench_v1.py

@@ -23,7 +23,7 @@ import pytest
 
 from ereuse_devicehub.resources.action.models import BenchmarkDataStorage, BenchmarkProcessor, \
     VisualTest
-from ereuse_devicehub.resources.action.rate.workbench.v1_0 import DataStorageRate, ProcessorRate, \
+from ereuse_devicehub.resources.action.rate.v1_0 import DataStorageRate, ProcessorRate, \
     RamRate, RateAlgorithm
 from ereuse_devicehub.resources.device.models import Desktop, HardDrive, Processor, RamModule
 from ereuse_devicehub.resources.enums import AppearanceRange, ComputerChassis, FunctionalityRange