Merge branch 'release/3.15.0'

Author: jimbonothing64

.github/workflows/auto-merge-dependency-updates.yaml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2.0.0
+        uses: dependabot/fetch-metadata@v2.1.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
       - name: Approve

.github/workflows/test-and-deploy.yaml

@@ -68,6 +68,8 @@ jobs:
         with:
           files: ./csfieldguide/coverage.xml
           verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   test-management:
     name: Tests - Management
@@ -84,6 +86,8 @@ jobs:
         with:
           files: ./csfieldguide/coverage.xml
           verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   test-style:
     name: Tests - Style

.readthedocs.yaml

@@ -0,0 +1,64 @@
+# Read the Docs configuration file for Sphinx projects
+
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+
+# Required
+
+version: 2
+
+
+# Set the OS, Python version and other tools you might need
+
+build:
+
+  os: ubuntu-22.04
+
+  tools:
+
+    python: "3.12"
+
+    # You can also specify other tool versions:
+
+    # nodejs: "20"
+
+    # rust: "1.70"
+
+    # golang: "1.20"
+
+
+# Build documentation in the "docs/" directory with Sphinx
+
+sphinx:
+
+  configuration: docs/conf.py
+
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+
+  # builder: "dirhtml"
+
+  # Fail on all warnings to avoid broken references
+
+  # fail_on_warning: true
+
+
+# Optionally build your docs in additional formats such as PDF and ePub
+
+# formats:
+
+#   - pdf
+
+#   - epub
+
+
+# Optional but recommended, declare the Python requirements required
+
+# to build your documentation
+
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+
+# python:
+
+#   install:
+
+#     - requirements: docs/requirements.txt

csfieldguide/appendices/management/commands/_AppendicesLoader.py

@@ -1,10 +1,13 @@
 """Custom loader for loading appendices."""
 
+from django.db import transaction
+from appendices.models import Appendix
 from utils.TranslatableModelLoader import TranslatableModelLoader
 from utils.errors.MissingRequiredFieldError import MissingRequiredFieldError
 from utils.errors.InvalidYAMLValueError import InvalidYAMLValueError
 from django.template.loader import get_template
 from django.template import TemplateDoesNotExist
+from django.urls import reverse, NoReverseMatch
 
 
 class AppendicesLoader(TranslatableModelLoader):
@@ -19,36 +22,68 @@ def __init__(self, factory, **kwargs):
         super().__init__(**kwargs)
         self.factory = factory
 
-    def check_template(self, page_data, type):
-        """Check template in page_data is valid.
+    @transaction.atomic
+    def load(self):
+        """Load appendices pages.
 
-        Args:
-            page_data (dict): Dictionary of page data.
-            type (str): Name of type of page.
+        Raise:
+            MissingRequiredFieldError: when no object can be found with the matching
+                attribute.
+            InvalidYAMLValueError: when invalid template path given or missing valid URL in urls.
+        """
+        appendix_pages = self.load_yaml_file(self.structure_file_path)
 
-        Returns:
-            A valid template as string.
+        for (slug, page_data) in appendix_pages.items():
+            try:
+                template = page_data["template"]
+            except (TypeError, KeyError):
+                raise MissingRequiredFieldError(
+                    self.structure_file_path,
+                    [
+                        "template",
+                    ],
+                    "Appendix"
+                )
 
-        Raises:
-            MissingRequiredFieldError: If template value not given.
-            InvalidYAMLValueError: If invalid template path given.
-        """
-        try:
-            template = page_data["template"]
-        except (TypeError, KeyError):
-            raise MissingRequiredFieldError(
-                self.structure_file_path,
-                [
+            # Check template is valid
+            try:
+                get_template(template)
+            except TemplateDoesNotExist:
+                raise InvalidYAMLValueError(
+                    self.structure_file_path,
                     "template",
-                ],
-                type
-            )
-        try:
-            get_template(template)
-        except TemplateDoesNotExist:
-            raise InvalidYAMLValueError(
-                self.structure_file_path,
-                "template ({})".format(template),
-                "A valid template file path"
+                    "A valid template file path"
+                )
+
+            # Check URL name is valid
+            url_name = f"appendices:{slug}"
+            try:
+                reverse(url_name)
+            except NoReverseMatch:
+                raise InvalidYAMLValueError(
+                    self.structure_file_path,
+                    f"<{slug}>",
+                    f"A URL name listed in 'csfieldguide/appendices/urls.py' matching '{url_name}'."
+                )
+
+            # Get Title Case from kebab-case name
+            name = slug.title().replace('-', ' ')
+
+            appendix_page, created = Appendix.objects.update_or_create(
+                slug=slug,
+                defaults={
+                    'name': name,
+                    'template': template,
+                    'url_name': url_name,
+                }
             )
-        return template
+            appendix_page.save()
+            if created:
+                term = 'Created'
+            else:
+                term = 'Updated'
+            self.log(f'{term} appendix page: {name}')
+
+        Appendix.objects.exclude(slug__in=appendix_pages.keys()).delete()
+
+        self.log("All appendix pages loaded!\n")

csfieldguide/appendices/management/commands/loadappendices.py

@@ -24,5 +24,6 @@ def handle(self, *args, **options):
             base_path=base_path
         )
 
+        loader.load()
         loader.log("All appendices loaded!")
         loader.log("")

csfieldguide/appendices/migrations/0008_initial.py

@@ -0,0 +1,25 @@
+# Generated by Django 4.2.9 on 2024-02-01 03:19
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('appendices', '0007_auto_20190209_2354'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='AppendixPage',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('slug', models.SlugField(unique=True)),
+                ('name', models.CharField(max_length=100)),
+                ('template', models.CharField(max_length=100)),
+                ('url_name', models.CharField(max_length=100)),
+            ],
+        ),
+    ]

csfieldguide/appendices/migrations/0009_appendix_delete_appendixpage.py

@@ -0,0 +1,26 @@
+# Generated by Django 4.2.9 on 2024-02-02 01:48
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('appendices', '0008_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Appendix',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('slug', models.SlugField(unique=True)),
+                ('name', models.CharField(max_length=100)),
+                ('template', models.CharField(max_length=100)),
+                ('url_name', models.CharField(max_length=100)),
+            ],
+        ),
+        migrations.DeleteModel(
+            name='AppendixPage',
+        ),
+    ]

csfieldguide/appendices/models.py

@@ -0,0 +1,54 @@
+"""Models for the appendices application."""
+
+from django.db import models
+from django.urls import reverse
+from django.utils.translation import gettext_lazy as _
+from search.utils import get_template_text
+
+
+class Appendix(models.Model):
+    """Model for appendix page in database."""
+
+    MODEL_NAME = _("Appendix")
+
+    #  Auto-incrementing 'id' field is automatically set by Django
+    slug = models.SlugField(unique=True)
+    name = models.CharField(max_length=100)
+    template = models.CharField(max_length=100)
+    url_name = models.CharField(max_length=100)
+
+    def get_absolute_url(self):
+        """Return the canonical URL for a Appendix.
+
+        Returns:
+            URL as string.
+        """
+        return reverse(self.url_name)
+
+    def __str__(self):
+        """Text representation of Appendix object.
+
+        Returns:
+            Name of page (str).
+        """
+        return self.name
+
+    def index_contents(self):
+        """Return dictionary for search indexing.
+
+        Returns:
+            Dictionary of content for search indexing. The dictionary keys
+            are the weightings of content, and the dictionary values
+            are strings of content to index.
+        """
+        return {
+            'A': self.name,
+            'B': get_template_text(self.template),
+        }
+
+    class Meta:
+        """Set consistent ordering of appendices."""
+
+        ordering = ["name"]
+        verbose_name = _("appendix")
+        verbose_name_plural = _("appendices")

csfieldguide/chapters/content/en/big-data/sections/analysis.md

@@ -73,7 +73,7 @@ Here are two prominent examples:
 - This is used for investigating social structures using networks.
 You can imagine how this works by thinking about the structure of Facebook.
 You and everyone else on Facebook are each an individual node, and two people are connected by an edge if they are Facebook friends.
-Together, these nodes and edges make a graph structure (a different type of [graph](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)) to the ones you normally see in maths) that can be analysed.
+Together, these nodes and edges make a graph structure (a different type of [graph](https://en.wikipedia.org/wiki/Graph_%28discrete_mathematics%29) to the ones you normally see in maths) that can be analysed.
 
 {image file-path="img/chapters/social-network-graph.png" caption="true" alt="Five circles with different names in them are shown with lines connecting each of them to illustrate that they are connected on social media. Each of these circles is then connected to several smaller circles, which represent other friends in their network."}
 

csfieldguide/chapters/content/en/coding-error-control/sections/the-parity-magic-trick.md

@@ -56,7 +56,7 @@ The original 7x7 cards that the computer laid out for you could be some kind of
 Although they are laid out in a grid, on a computer the rows of bits would be stored or transmitted one after the other (as 8 lots of 8 bits).
 
 The extra cards you added are called *parity bits*.
-[Parity](https://en.wikipedia.org/wiki/Parity_(mathematics))
+[Parity](https://en.wikipedia.org/wiki/Parity_%28mathematics%29)
 simply means whether a number is even or odd (the word comes from the same root as "pair").
 By adding the extra cards in a way that ensured an even number of black cards in each row and column, you made it so that the rows and columns had what is called *even parity*.
 

csfieldguide/chapters/content/en/coding-introduction/sections/further-reading.md

@@ -5,7 +5,7 @@ James Gleick's book [The Information: A History, a Theory, a Flood](http://www.a
 ## Useful links
 
 - A good collection of resources related to all three kinds of coding is available in the [Bletchley Park Codes Resources](http://www.cimt.org.uk/resources/codes/)
-- [Entropy and information theory](https://en.wikipedia.org/wiki/Entropy_(information_theory))
+- [Entropy and information theory](https://en.wikipedia.org/wiki/Entropy_%28information_theory%29)
 - [History of information theory and its relationship to entropy in thermodynamics](https://en.wikipedia.org/wiki/History_of_entropy#Information_theory)
 - [Timeline of information theory](https://en.wikipedia.org/wiki/Timeline_of_information_theory)
 - [Shannon's seminal work in information theory](https://en.wikipedia.org/wiki/A_Mathematical_Theory_of_Communication)

csfieldguide/chapters/content/en/complexity-and-tractability/sections/other-intractable-problems.md

@@ -19,4 +19,4 @@ Extra sections will eventually be added here to introduce some of them, but in t
 - [Longest path](https://en.wikipedia.org/wiki/Longest_path) (this is interesting because finding the longest path is intractable, yet finding the shortest path is tractable - the shortest path is calculated when a GPS device works out the shortest route to a destination.
   Also, a Hamiltonian problem can be reduced easily to longest path, showing the concept of reduction when one NP-complete problem is used to solve another).
   [Here's a song about it!](https://www.youtube.com/watch?feature=player_embedded&v=a3ww0gwEszo)
-- [The Battleship problem](https://en.wikipedia.org/wiki/Battleship_(puzzle))
+- [The Battleship problem](https://en.wikipedia.org/wiki/Battleship_%28puzzle%29)

csfieldguide/chapters/content/en/computer-graphics/sections/further-reading.md

@@ -3,5 +3,5 @@
 - [Computer graphics on Wikipedia](https://en.wikipedia.org/wiki/Computer_graphics)
 - [Transformation matrix on Wikipedia](https://en.wikipedia.org/wiki/Transformation_matrix)
 - [Bresenham's line algorithm on Wikipedia](https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm)
-- [Ray tracing on Wikipedia](https://en.wikipedia.org/wiki/Ray_tracing_(graphics))
+- [Ray tracing on Wikipedia](https://en.wikipedia.org/wiki/Ray_tracing_%28graphics%29)
 - [3D tutorials from POV-Ray](http://www.povray.org/resources/links/3D_Tutorials/POV-Ray_Tutorials/)

csfieldguide/chapters/content/en/human-computer-interaction/sections/mātāpono-māori.md renamed to csfieldguide/chapters/content/en/human-computer-interaction/sections/maataapono-maaori.md

@@ -6,7 +6,7 @@
 - [Wikipedia – Software crisis](https://en.wikipedia.org/wiki/Software_crisis)
 - [IEEE – Why software fails](http://spectrum.ieee.org/computing/software/why-software-fails)
 - [Wikipedia – Software design](https://en.wikipedia.org/wiki/Software_design)
-- [Wikipedia – Abstraction](https://en.wikipedia.org/wiki/Abstraction_(computer_science))
+- [Wikipedia – Abstraction](https://en.wikipedia.org/wiki/Abstraction_%28computer_science%29)
 - [Wikipedia – Software testing](https://en.wikipedia.org/wiki/Software_testing)
 - [Wikipedia – Software development process](https://en.wikipedia.org/wiki/Software_development_process)
 - [Wikipedia – Waterfall model](https://en.wikipedia.org/wiki/Waterfall_model)

csfieldguide/chapters/content/en/software-engineering/sections/further-reading.md

@@ -10,8 +10,9 @@ interface-usability:
 usability-heuristics:
   section-number: 4
 
-mātāpono-māori:
+maataapono-maaori:
   section-number: 5
+  slug: mātāpono-māori
 
 accessibility:
   section-number: 6