prompt: We are currently solving the following issue within our repository. Here is the issue text:
  --- BEGIN ISSUE ---
  Feature Request: Document the results framework
  ### What are you trying to do?
  
  Understand how the results framework functions
  
  ### Describe the solution you'd like
  
  A technical documentation of how it works.
  
  ### Have you consider alternatives?
  
  _No response_
  
  ### Additional context
  
  _No response_
  
  --- END ISSUE ---
  
  Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
  --- BEGIN FILES ---
  Path: `akvo/rsr/models/project_hierarchy.py`
  Content:
  ```
  1 # -*- coding: utf-8 -*-
  2 
  3 # Akvo RSR is covered by the GNU Affero General Public License.
  4 # See more details in the license.txt file located at the root folder of the Akvo RSR module.
  5 # For additional details on the GNU license please see < http://www.gnu.org/licenses/agpl.html >.
  6 
  7 from django.db import models
  8 from django.utils.translation import ugettext_lazy as _
  9 
  10 
  11 class ProjectHierarchy(models.Model):
  12     project_relation = 'projecthierarchy__in'
  13     root_project = models.OneToOneField('Project', on_delete=models.CASCADE, db_index=True)
  14     max_depth = models.PositiveSmallIntegerField()
  15     is_master = models.BooleanField(_('is master program'), default=False)
  16 
  17     class Meta:
  18         app_label = 'rsr'
  19         verbose_name = _('program')
  20         verbose_name_plural = _('programs')
  21         ordering = ['-id']
  22 
  23     @property
  24     def descendants(self):
  25         return self.root_project.descendants(max_depth=self.max_depth)
  26 
  27     @property
  28     def project_count(self):
  29         return self.descendants.count() - 1  # remove root_project from count
  30 
  31     @property
  32     def project_ids(self):
  33         return self.descendants.values_list('id', flat=True)
  34 
  35     @property
  36     def organisation(self):
  37         return self.root_project.reporting_org
  38 
  39     def __str__(self):
  40         return self.root_project.title
  41
  ```
  
  Path: `doc/conf.py`
  Content:
  ```
  1 # Configuration file for the Sphinx documentation builder.
  2 #
  3 # For the full list of built-in configuration values, see the documentation:
  4 # https://www.sphinx-doc.org/en/master/usage/configuration.html
  5 
  6 # -- Project information -----------------------------------------------------
  7 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
  8 
  9 import os
  10 import sys
  11 import django
  12 sys.path.insert(0, os.path.abspath('..'))
  13 os.environ['DJANGO_SETTINGS_MODULE'] = 'akvo.settings'
  14 django.setup()
  15 
  16 project = 'Akvo RSR'
  17 copyright = '2023, Akvo Foundation'
  18 author = 'Akvo Foundation'
  19 
  20 # -- General configuration ---------------------------------------------------
  21 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
  22 
  23 extensions = [
  24     'sphinx.ext.autodoc',
  25     'sphinx.ext.autosummary',
  26     'sphinx.ext.viewcode',
  27     'myst_parser',
  28 ]
  29 
  30 templates_path = ['_templates']
  31 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  32 
  33 
  34 
  35 # -- Options for HTML output -------------------------------------------------
  36 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
  37 
  38 html_theme = 'cloud'
  39 html_static_path = ['_static']
  40
  ```
  --- END FILES ---
  
  Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.
  
  Here is an example:
  
  ```diff
  diff --git a/examples/server_async.py b/examples/server_async.py
  --- a/examples/server_async.py
  +++ b/examples/server_async.py
  @@ -313,4 +313,4 @@
   
   
   if __name__ == "__main__":
  -    asyncio.run(run_async_server("."), debug=True)
  +    asyncio.run(run_async_server(), debug=True)
  diff --git a/examples/server_sync.py b/examples/server_sync.py
  --- a/examples/server_sync.py
  +++ b/examples/server_sync.py
  @@ -313,5 +313,5 @@
   
   
   if __name__ == "__main__":
  -    server = run_sync_server(".")
  +    server = run_sync_server()
       server.shutdown()
  
  ```
  
golden_diff: diff --git a/akvo/rsr/models/project_hierarchy.py b/akvo/rsr/models/project_hierarchy.py
  --- a/akvo/rsr/models/project_hierarchy.py
  +++ b/akvo/rsr/models/project_hierarchy.py
  @@ -9,10 +9,22 @@
   
   
   class ProjectHierarchy(models.Model):
  +    """
  +    The actual "Program" with a project hierarchy.
  +    """
       project_relation = 'projecthierarchy__in'
  +
       root_project = models.OneToOneField('Project', on_delete=models.CASCADE, db_index=True)
  +    """
  +    The root of the program
  +    It can be used to create subprograms / a program tree
  +    """
  +
       max_depth = models.PositiveSmallIntegerField()
  +    """TODO: It is unclear why this field currently exists"""
  +
       is_master = models.BooleanField(_('is master program'), default=False)
  +    """Used when an organisation has one program under which they would like to create subprograms"""
   
       class Meta:
           app_label = 'rsr'
  @@ -22,10 +34,15 @@
   
       @property
       def descendants(self):
  +        """
  +        The entire tree in a list.
  +        No order is guaranteed
  +        """
           return self.root_project.descendants(max_depth=self.max_depth)
   
       @property
       def project_count(self):
  +        """The number of children without counting the root project"""
           return self.descendants.count() - 1  # remove root_project from count
   
       @property
  @@ -34,6 +51,7 @@
   
       @property
       def organisation(self):
  +        """The reporting organisation of the tree"""
           return self.root_project.reporting_org
   
       def __str__(self):
  diff --git a/doc/conf.py b/doc/conf.py
  --- a/doc/conf.py
  +++ b/doc/conf.py
  @@ -21,6 +21,7 @@
   # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
   
   extensions = [
  +    'sphinxcontrib.plantuml',
       'sphinx.ext.autodoc',
       'sphinx.ext.autosummary',
       'sphinx.ext.viewcode',
  @@ -30,7 +31,9 @@
   templates_path = ['_templates']
   exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
   
  -
  +myst_enable_extensions = [
  +    "colon_fence",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence
  +]
   
   # -- Options for HTML output -------------------------------------------------
   # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
  
verification_info: {"golden_diff": "diff --git a/akvo/rsr/models/project_hierarchy.py b/akvo/rsr/models/project_hierarchy.py\n--- a/akvo/rsr/models/project_hierarchy.py\n+++ b/akvo/rsr/models/project_hierarchy.py\n@@ -9,10 +9,22 @@\n \n \n class ProjectHierarchy(models.Model):\n+    \"\"\"\n+    The actual \"Program\" with a project hierarchy.\n+    \"\"\"\n     project_relation = 'projecthierarchy__in'\n+\n     root_project = models.OneToOneField('Project', on_delete=models.CASCADE, db_index=True)\n+    \"\"\"\n+    The root of the program\n+    It can be used to create subprograms / a program tree\n+    \"\"\"\n+\n     max_depth = models.PositiveSmallIntegerField()\n+    \"\"\"TODO: It is unclear why this field currently exists\"\"\"\n+\n     is_master = models.BooleanField(_('is master program'), default=False)\n+    \"\"\"Used when an organisation has one program under which they would like to create subprograms\"\"\"\n \n     class Meta:\n         app_label = 'rsr'\n@@ -22,10 +34,15 @@\n \n     @property\n     def descendants(self):\n+        \"\"\"\n+        The entire tree in a list.\n+        No order is guaranteed\n+        \"\"\"\n         return self.root_project.descendants(max_depth=self.max_depth)\n \n     @property\n     def project_count(self):\n+        \"\"\"The number of children without counting the root project\"\"\"\n         return self.descendants.count() - 1  # remove root_project from count\n \n     @property\n@@ -34,6 +51,7 @@\n \n     @property\n     def organisation(self):\n+        \"\"\"The reporting organisation of the tree\"\"\"\n         return self.root_project.reporting_org\n \n     def __str__(self):\ndiff --git a/doc/conf.py b/doc/conf.py\n--- a/doc/conf.py\n+++ b/doc/conf.py\n@@ -21,6 +21,7 @@\n # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration\n \n extensions = [\n+    'sphinxcontrib.plantuml',\n     'sphinx.ext.autodoc',\n     'sphinx.ext.autosummary',\n     'sphinx.ext.viewcode',\n@@ -30,7 +31,9 @@\n templates_path = ['_templates']\n exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n \n-\n+myst_enable_extensions = [\n+    \"colon_fence\",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence\n+]\n \n # -- Options for HTML output -------------------------------------------------\n # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output\n", "issue": "Feature Request: Document the results framework\n### What are you trying to do?\n\nUnderstand how the results framework functions\n\n### Describe the solution you'd like\n\nA technical documentation of how it works.\n\n### Have you consider alternatives?\n\n_No response_\n\n### Additional context\n\n_No response_\n", "before_files": [{"content": "# -*- coding: utf-8 -*-\n\n# Akvo RSR is covered by the GNU Affero General Public License.\n# See more details in the license.txt file located at the root folder of the Akvo RSR module.\n# For additional details on the GNU license please see < http://www.gnu.org/licenses/agpl.html >.\n\nfrom django.db import models\nfrom django.utils.translation import ugettext_lazy as _\n\n\nclass ProjectHierarchy(models.Model):\n    project_relation = 'projecthierarchy__in'\n    root_project = models.OneToOneField('Project', on_delete=models.CASCADE, db_index=True)\n    max_depth = models.PositiveSmallIntegerField()\n    is_master = models.BooleanField(_('is master program'), default=False)\n\n    class Meta:\n        app_label = 'rsr'\n        verbose_name = _('program')\n        verbose_name_plural = _('programs')\n        ordering = ['-id']\n\n    @property\n    def descendants(self):\n        return self.root_project.descendants(max_depth=self.max_depth)\n\n    @property\n    def project_count(self):\n        return self.descendants.count() - 1  # remove root_project from count\n\n    @property\n    def project_ids(self):\n        return self.descendants.values_list('id', flat=True)\n\n    @property\n    def organisation(self):\n        return self.root_project.reporting_org\n\n    def __str__(self):\n        return self.root_project.title\n", "path": "akvo/rsr/models/project_hierarchy.py"}, {"content": "# Configuration file for the Sphinx documentation builder.\n#\n# For the full list of built-in configuration values, see the documentation:\n# https://www.sphinx-doc.org/en/master/usage/configuration.html\n\n# -- Project information -----------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information\n\nimport os\nimport sys\nimport django\nsys.path.insert(0, os.path.abspath('..'))\nos.environ['DJANGO_SETTINGS_MODULE'] = 'akvo.settings'\ndjango.setup()\n\nproject = 'Akvo RSR'\ncopyright = '2023, Akvo Foundation'\nauthor = 'Akvo Foundation'\n\n# -- General configuration ---------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary',\n    'sphinx.ext.viewcode',\n    'myst_parser',\n]\n\ntemplates_path = ['_templates']\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n\n\n\n# -- Options for HTML output -------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output\n\nhtml_theme = 'cloud'\nhtml_static_path = ['_static']\n", "path": "doc/conf.py"}], "after_files": [{"content": "# -*- coding: utf-8 -*-\n\n# Akvo RSR is covered by the GNU Affero General Public License.\n# See more details in the license.txt file located at the root folder of the Akvo RSR module.\n# For additional details on the GNU license please see < http://www.gnu.org/licenses/agpl.html >.\n\nfrom django.db import models\nfrom django.utils.translation import ugettext_lazy as _\n\n\nclass ProjectHierarchy(models.Model):\n    \"\"\"\n    The actual \"Program\" with a project hierarchy.\n    \"\"\"\n    project_relation = 'projecthierarchy__in'\n\n    root_project = models.OneToOneField('Project', on_delete=models.CASCADE, db_index=True)\n    \"\"\"\n    The root of the program\n    It can be used to create subprograms / a program tree\n    \"\"\"\n\n    max_depth = models.PositiveSmallIntegerField()\n    \"\"\"TODO: It is unclear why this field currently exists\"\"\"\n\n    is_master = models.BooleanField(_('is master program'), default=False)\n    \"\"\"Used when an organisation has one program under which they would like to create subprograms\"\"\"\n\n    class Meta:\n        app_label = 'rsr'\n        verbose_name = _('program')\n        verbose_name_plural = _('programs')\n        ordering = ['-id']\n\n    @property\n    def descendants(self):\n        \"\"\"\n        The entire tree in a list.\n        No order is guaranteed\n        \"\"\"\n        return self.root_project.descendants(max_depth=self.max_depth)\n\n    @property\n    def project_count(self):\n        \"\"\"The number of children without counting the root project\"\"\"\n        return self.descendants.count() - 1  # remove root_project from count\n\n    @property\n    def project_ids(self):\n        return self.descendants.values_list('id', flat=True)\n\n    @property\n    def organisation(self):\n        \"\"\"The reporting organisation of the tree\"\"\"\n        return self.root_project.reporting_org\n\n    def __str__(self):\n        return self.root_project.title\n", "path": "akvo/rsr/models/project_hierarchy.py"}, {"content": "# Configuration file for the Sphinx documentation builder.\n#\n# For the full list of built-in configuration values, see the documentation:\n# https://www.sphinx-doc.org/en/master/usage/configuration.html\n\n# -- Project information -----------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information\n\nimport os\nimport sys\nimport django\nsys.path.insert(0, os.path.abspath('..'))\nos.environ['DJANGO_SETTINGS_MODULE'] = 'akvo.settings'\ndjango.setup()\n\nproject = 'Akvo RSR'\ncopyright = '2023, Akvo Foundation'\nauthor = 'Akvo Foundation'\n\n# -- General configuration ---------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration\n\nextensions = [\n    'sphinxcontrib.plantuml',\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary',\n    'sphinx.ext.viewcode',\n    'myst_parser',\n]\n\ntemplates_path = ['_templates']\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n\nmyst_enable_extensions = [\n    \"colon_fence\",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence\n]\n\n# -- Options for HTML output -------------------------------------------------\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output\n\nhtml_theme = 'cloud'\nhtml_static_path = ['_static']\n", "path": "doc/conf.py"}]}