diff --git a/.github/workflows/crowdin-actions.yaml b/.github/workflows/crowdin-actions.yaml index 0f853e20f4..f3d104c475 100644 --- a/.github/workflows/crowdin-actions.yaml +++ b/.github/workflows/crowdin-actions.yaml @@ -19,12 +19,12 @@ jobs: uses: actions/checkout@v3 - name: Upload or update source files to Crowdin - uses: crowdin/github-action@1.4.15 + uses: crowdin/github-action@1.4.16 with: upload_sources: true - name: Download German translations - uses: crowdin/github-action@1.4.15 + uses: crowdin/github-action@1.4.16 with: upload_sources: false download_translations: true @@ -42,7 +42,7 @@ jobs: config: crowdin.yaml - name: Download Spanish translations - uses: crowdin/github-action@1.4.15 + uses: crowdin/github-action@1.4.16 with: upload_sources: false download_translations: true diff --git a/csfieldguide/config/__init__.py b/csfieldguide/config/__init__.py index 01c0559016..a664eb9acf 100644 --- a/csfieldguide/config/__init__.py +++ b/csfieldguide/config/__init__.py @@ -1,3 +1,3 @@ """Module for Django system configuration.""" -__version__ = "3.12.2" +__version__ = "3.12.3" diff --git a/csfieldguide/package-lock.json b/csfieldguide/package-lock.json index c64b23cd60..90a58528c7 100644 --- a/csfieldguide/package-lock.json +++ b/csfieldguide/package-lock.json @@ -638,13 +638,13 @@ "dev": true }, "autoprefixer": { - "version": "10.4.12", - "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.12.tgz", - "integrity": "sha512-WrCGV9/b97Pa+jtwf5UGaRjgQIg7OK3D06GnoYoZNcG1Xb8Gt3EfuKjlhh9i/VtT16g6PYjZ69jdJ2g8FxSC4Q==", + "version": "10.4.13", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.13.tgz", + "integrity": "sha512-49vKpMqcZYsJjwotvt4+h/BCjJVnhGwcLpDt5xkcaOG3eLrG/HUYLagrihYsQ+qrIBgIzX1Rw7a6L8I/ZA1Atg==", "dev": true, "requires": { "browserslist": "^4.21.4", - "caniuse-lite": "^1.0.30001407", + "caniuse-lite": "^1.0.30001426", "fraction.js": "^4.2.0", "normalize-range": "^0.1.2", "picocolors": "^1.0.0", @@ -664,15 +664,15 @@ } }, "caniuse-lite": { - "version": "1.0.30001409", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001409.tgz", - "integrity": "sha512-V0mnJ5dwarmhYv8/MzhJ//aW68UpvnQBXv8lJ2QUsvn2pHcmAuNtu8hQEDz37XnA1iE+lRR9CIfGWWpgJ5QedQ==", + "version": "1.0.30001426", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001426.tgz", + "integrity": "sha512-n7cosrHLl8AWt0wwZw/PJZgUg3lV0gk9LMI7ikGJwhyhgsd2Nb65vKvmSexCqq/J7rbH3mFG6yZZiPR5dLPW5A==", "dev": true }, "electron-to-chromium": { - "version": "1.4.256", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.256.tgz", - "integrity": "sha512-x+JnqyluoJv8I0U9gVe+Sk2st8vF0CzMt78SXxuoWCooLLY2k5VerIBdpvG7ql6GKI4dzNnPjmqgDJ76EdaAKw==", + "version": "1.4.284", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.284.tgz", + "integrity": "sha512-M8WEXFuKXMYMVr45fo8mq0wUrrJHheiKZf6BArTKk9ZBYCKJEOU5H8cdWgDT+qCVZf7Na4lVUaZsA+h6uA9+PA==", "dev": true }, "node-releases": { @@ -688,9 +688,9 @@ "dev": true }, "update-browserslist-db": { - "version": "1.0.9", - "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.9.tgz", - "integrity": "sha512-/xsqn21EGVdXI3EXSum1Yckj3ZVZugqyOZQ/CxYPBD/R+ko9NSUScf8tFF4dOKY+2pvSSJA/S+5B8s4Zr4kyvg==", + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz", + "integrity": "sha512-OztqDenkfFkbSG+tRxBeAnCVPckDBcvibKd35yDONx6OU8N7sqgwc7rCbkJ/WcYtVRZ4ba68d6byhC21GFh7sQ==", "dev": true, "requires": { "escalade": "^3.1.1", diff --git a/csfieldguide/package.json b/csfieldguide/package.json index 465a560d23..ee9d116e7b 100644 --- a/csfieldguide/package.json +++ b/csfieldguide/package.json @@ -6,7 +6,7 @@ "dependencies": {}, "devDependencies": { "ansi-colors": "4.1.3", - "autoprefixer": "10.4.12", + "autoprefixer": "10.4.13", "bootstrap": "4.6.2", "browser-sync": "2.27.10", "browserify": "17.0.0", diff --git a/csfieldguide/static/img/csfg-icon-with-text-white.png b/csfieldguide/static/img/csfg-icon-with-text-white.png new file mode 100644 index 0000000000..d7441e9e02 Binary files /dev/null and b/csfieldguide/static/img/csfg-icon-with-text-white.png differ diff --git a/csfieldguide/static/img/csfg-icon-with-text.png b/csfieldguide/static/img/csfg-icon-with-text.png new file mode 100644 index 0000000000..1a33dda286 Binary files /dev/null and b/csfieldguide/static/img/csfg-icon-with-text.png differ diff --git a/csfieldguide/static/img/guide-favicon-white.png b/csfieldguide/static/img/guide-favicon-white.png new file mode 100644 index 0000000000..03d24ffcc1 Binary files /dev/null and b/csfieldguide/static/img/guide-favicon-white.png differ diff --git a/csfieldguide/static/img/guide-favicon.png b/csfieldguide/static/img/guide-favicon.png index 9dca303d55..55f843121c 100644 Binary files a/csfieldguide/static/img/guide-favicon.png and b/csfieldguide/static/img/guide-favicon.png differ diff --git a/csfieldguide/static/img/logos/guide-logo-light.png b/csfieldguide/static/img/logos/guide-logo-light.png deleted file mode 100644 index 9742b652eb..0000000000 Binary files a/csfieldguide/static/img/logos/guide-logo-light.png and /dev/null differ diff --git a/csfieldguide/static/interactives/cmy-mixer/scss/cmy-mixer.scss b/csfieldguide/static/interactives/cmy-mixer/scss/cmy-mixer.scss index e6f2fe179c..4ca87fff6b 100644 --- a/csfieldguide/static/interactives/cmy-mixer/scss/cmy-mixer.scss +++ b/csfieldguide/static/interactives/cmy-mixer/scss/cmy-mixer.scss @@ -1,4 +1,4 @@ -@import "node_modules/nouislider/distribute/nouislider.css"; +@import "static/interactives/cmy-mixer/node_modules/nouislider/distribute/nouislider"; @import "node_modules/bootstrap/scss/functions"; @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins"; diff --git a/csfieldguide/static/interactives/colour-matcher/scss/colour-matcher.scss b/csfieldguide/static/interactives/colour-matcher/scss/colour-matcher.scss index 6831061236..215e7d8551 100644 --- a/csfieldguide/static/interactives/colour-matcher/scss/colour-matcher.scss +++ b/csfieldguide/static/interactives/colour-matcher/scss/colour-matcher.scss @@ -1,4 +1,4 @@ -@import "node_modules/nouislider/distribute/nouislider.css"; +@import "static/interactives/colour-matcher/node_modules/nouislider/distribute/nouislider"; /* Distance between bottom of slider and pips */ #interactive-colour-matcher .noUi-pips { diff --git a/csfieldguide/static/interactives/data-bias/css/data-bias.scss b/csfieldguide/static/interactives/data-bias/css/data-bias.scss index 7350b783e8..25da1f0139 100644 --- a/csfieldguide/static/interactives/data-bias/css/data-bias.scss +++ b/csfieldguide/static/interactives/data-bias/css/data-bias.scss @@ -1,4 +1,4 @@ -@import "node_modules/nouislider/distribute/nouislider.css"; +@import "static/interactives/data-bias/node_modules/nouislider/distribute/nouislider"; @import "node_modules/bootstrap/scss/functions"; @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins"; diff --git a/csfieldguide/static/interactives/matrix-simplifier/js/matrix-simplifier.js b/csfieldguide/static/interactives/matrix-simplifier/js/matrix-simplifier.js index ba54464cfa..963f574860 100644 --- a/csfieldguide/static/interactives/matrix-simplifier/js/matrix-simplifier.js +++ b/csfieldguide/static/interactives/matrix-simplifier/js/matrix-simplifier.js @@ -1,5 +1,5 @@ const dragula = require('dragula'); -const mathjs = require('mathjs'); +const mathjs_import = require('mathjs'); const sprintf = require('sprintf-js').sprintf; const vsprintf = require('sprintf-js').vsprintf; @@ -18,7 +18,7 @@ const MATRIX_CHILD_INDEX = 3; // Index for which child of the draggable element/ * Below is adapted from https://mathjs.org/examples/browser/angle_configuration.html.html * This is used to configure mathjs to accept degrees as input for trig functions. */ - +const mathjs = mathjs_import.create(mathjs_import.all); let replacements = {}; // the trigonometric functions that we are configuring to handle inputs of degrees instead of radians @@ -90,7 +90,7 @@ var resultEqtn; // only show equations once they are rendered // URL for mathjax script loaded from CDN -var mjaxURL = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML,Safe.js'; +var mjaxURL = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-AMS-MML_HTMLorMML,Safe.js'; // load mathjax script $.getScript(mjaxURL, function() { // mathjax successfully loaded, let it render @@ -595,11 +595,11 @@ function populateModalForEditing() { $('#matrix-row-0-col-0').val(matrix[0][0]); $('#matrix-row-0-col-1').val(matrix[0][1]); $('#matrix-row-0-col-2').val(matrix[0][2]); - + $('#matrix-row-1-col-0').val(matrix[1][0]); $('#matrix-row-1-col-1').val(matrix[1][1]); $('#matrix-row-1-col-2').val(matrix[1][2]); - + $('#matrix-row-2-col-0').val(matrix[2][0]); $('#matrix-row-2-col-1').val(matrix[2][1]); $('#matrix-row-2-col-2').val(matrix[2][2]); diff --git a/csfieldguide/static/interactives/matrix-simplifier/scss/matrix-simplifier.scss b/csfieldguide/static/interactives/matrix-simplifier/scss/matrix-simplifier.scss index 131c2bfa20..ca271a9df4 100644 --- a/csfieldguide/static/interactives/matrix-simplifier/scss/matrix-simplifier.scss +++ b/csfieldguide/static/interactives/matrix-simplifier/scss/matrix-simplifier.scss @@ -1,4 +1,4 @@ -@import "node_modules/dragula/dist/dragula.css"; +@import "static/interactives/matrix-simplifier/node_modules/dragula/dist/dragula"; @import "node_modules/bootstrap/scss/functions"; @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins"; @@ -81,19 +81,13 @@ } } -#output-container { - > div { - > span { - display: inline !important; - } - } -} - +#output-container > div { + display: flex; + align-items: center; + justify-content: center; -#matrix-output, -#vector-output { - > span { - display: inline !important; + .MathJax_Display { + width: min-content; } } diff --git a/csfieldguide/static/interactives/pixel-viewer/README.md b/csfieldguide/static/interactives/pixel-viewer/README.md index 796cea16ec..7375dea1ee 100644 --- a/csfieldguide/static/interactives/pixel-viewer/README.md +++ b/csfieldguide/static/interactives/pixel-viewer/README.md @@ -1,6 +1,6 @@ # Pixel Viewer Interactive -**Author:** Jack Morgan +**Author:** Jack Morgan **Modified by:** Andy Bell, Courtney Bracefield, Alasdair Smith, Jack Morgan This interactive is created to allow users to see the values of each pixel of an image. @@ -29,6 +29,7 @@ The interactive has the following optional parameters to configure the interacti - `image` - Filename of image to use (for example `arnold.jpg`). - `picturepicker` - Displays a set of pictures available for using. - `hide-menu` - Hides the menu. +- `hide-colour-codes` - Hides the colour codes within pixels. - `hide-colour-code-picker` - Hides the option to change between colour code formats. - `hide-config-selector` - Hides the option to change between modes. - `no-pixel-fill` - Displays pixels without background fill from start (also doesn't show initial image with transition). diff --git a/csfieldguide/static/interactives/pixel-viewer/js/pixel-viewer.js b/csfieldguide/static/interactives/pixel-viewer/js/pixel-viewer.js index e1c664439a..30547f89c2 100644 --- a/csfieldguide/static/interactives/pixel-viewer/js/pixel-viewer.js +++ b/csfieldguide/static/interactives/pixel-viewer/js/pixel-viewer.js @@ -1,9 +1,10 @@ // Settings and intialize layout this.MAX_HEIGHT = 133; this.CELL_SIZE = 50; - this.MAX_NOISE = 15; +var searchParameters = new URL(window.location.href).searchParams; + this.container = document.getElementById("pixel-viewer-interactive-container"); this.content = document.getElementById("pixel-viewer-interactive-content"); this.context = content.getContext('2d'); @@ -15,8 +16,8 @@ this.contentHeight = 6650; this.cell_line_height = 15; this.cell_text = 'R \nG \nB '; this.text_opacity = 0; - this.mode = 'datarep'; +var showColourCode = true; this.picturePicker = false; this.filter = null; @@ -73,15 +74,15 @@ var colour_code_rep = 'rgb'; $( document ).ready(function() { init_cache(300, MAX_HEIGHT); - if (getUrlParameter('image')){ - image_filename = getUrlParameter('image'); + if (searchParameters.has('image')){ + image_filename = searchParameters.get('image'); } var image_filepath = image_base_path + image_filename; $('#pixel-viewer-interactive-original-image').attr('crossorigin', 'anonymous').attr('src', image_filepath); load_resize_image(image_filepath, false); - switch(getUrlParameter('mode')) { + switch (searchParameters.get('mode')) { case 'threshold': mode = 'threshold'; break; case 'thresholdgreyscale': @@ -94,24 +95,28 @@ $( document ).ready(function() { mode = 'brightness'; break; } - if (getUrlParameter('picturepicker')){ + if (searchParameters.has('picturepicker')){ // Whether or not to allow student to pick from set pictures picturePicker = true; } - if (getUrlParameter('hide-menu')) { + if (searchParameters.has('hide-menu')) { $('#pixel-viewer-interactive-menu-toggle').remove(); } - if (getUrlParameter('pixelmania')){ + if (searchParameters.has('hide-colour-codes')) { + showColourCode = false; + } + + if (searchParameters.has('pixelmania')){ $('#pixelmania-logo').removeClass('d-none'); } - if (getUrlParameter('hide-colour-code-picker')) { + if (searchParameters.has('hide-colour-code-picker')) { $("#colour-code-radio").addClass('d-none').removeClass('d-flex'); } - if (getUrlParameter('hide-config-selector')) { + if (searchParameters.has('hide-config-selector')) { $("#configSelector").addClass('d-none'); } @@ -120,7 +125,7 @@ $( document ).ready(function() { createPicturePicker(); } - colour_code_rep = getUrlParameter('colour-code'); + colour_code_rep = searchParameters.get('colour-code'); if (colour_code_rep == 'rgb-hex') { $("input[id='rgb-hex-colour-code']").prop('checked', true); } else if (colour_code_rep == 'hex') { @@ -149,7 +154,7 @@ $( document ).ready(function() { scroller_position_left = image_position_left; reflow(); - if (getUrlParameter('no-pixel-fill')){ + if (searchParameters.has('no-pixel-fill')){ $('#pixel-viewer-interactive-show-pixel-fill').prop('checked', false); $("#pixel-viewer-interactive-loader").hide(); $("#pixel-viewer-interactive-buttons").css({opacity: 1}); @@ -1066,7 +1071,7 @@ var paint = function(row, col, left, top, width, height, zoom) { } // If text opacity is greater than 0, then display RGB values -if (text_opacity > 0) { + if (showColourCode && text_opacity > 0) { if (!show_pixel_fill) { context.fillStyle = "rgba(0, 0, 0, " + text_opacity + ")"; } else if ((((pixelData[0] / 255) + (pixelData[1] / 255) + (pixelData[2] / 255)) / 3) < 0.85) { @@ -1126,7 +1131,7 @@ var reflow = function() { }; // Set zoom to see numbers if no colour fill -if (getUrlParameter('no-pixel-fill')) { +if (searchParameters.has('no-pixel-fill')) { this.scroller.zoomTo(1.5); } @@ -1239,19 +1244,3 @@ function sum(array){ return prev + curr; }); } - -// From jquerybyexample.net/2012/06/get-url-parameters-using-jquery.html -function getUrlParameter(sParam) { - var sPageURL = decodeURIComponent(window.location.search.substring(1)), - sURLVariables = sPageURL.split('&'), - sParameterName, - i; - - for (i = 0; i < sURLVariables.length; i++) { - sParameterName = sURLVariables[i].split('='); - - if (sParameterName[0] === sParam) { - return sParameterName[1] === undefined ? true : sParameterName[1]; - } - } -}; diff --git a/csfieldguide/static/interactives/pixel-viewer/scss/pixel-viewer.scss b/csfieldguide/static/interactives/pixel-viewer/scss/pixel-viewer.scss index 540ed74ac9..89193d6870 100644 --- a/csfieldguide/static/interactives/pixel-viewer/scss/pixel-viewer.scss +++ b/csfieldguide/static/interactives/pixel-viewer/scss/pixel-viewer.scss @@ -6,6 +6,8 @@ user-select: none !important; background-color: #3f51b5; flex-grow: 1; + height: 100vh; + overflow: hidden; #pixel-viewer-interactive-source-canvas { height: 133px; diff --git a/csfieldguide/static/interactives/scene-editor/package.json b/csfieldguide/static/interactives/scene-editor/package.json index 658f663050..293cf42477 100644 --- a/csfieldguide/static/interactives/scene-editor/package.json +++ b/csfieldguide/static/interactives/scene-editor/package.json @@ -4,7 +4,7 @@ "private": true, "dependencies": { "mathjs": "6.0.3", - "three": "0.145.0", + "three": "0.146.0", "three-orbit-controls": "82.1.0", "sprintf-js": "1.1.2" } diff --git a/csfieldguide/static/interactives/sorting-algorithms/scss/sorting-algorithms.scss b/csfieldguide/static/interactives/sorting-algorithms/scss/sorting-algorithms.scss index 141504eaed..899fedcd62 100644 --- a/csfieldguide/static/interactives/sorting-algorithms/scss/sorting-algorithms.scss +++ b/csfieldguide/static/interactives/sorting-algorithms/scss/sorting-algorithms.scss @@ -1,5 +1,5 @@ @use "sass:math"; -@import "node_modules/dragula/dist/dragula.css"; +@import "static/interactives/sorting-algorithms/node_modules/dragula/dist/dragula"; @import "node_modules/bootstrap/scss/functions"; @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins"; @@ -61,7 +61,7 @@ z-index: 1; } -// Partial copy of its namesake from Dragula.css +// Partial copy of its namesake from Dragula // but !important to override changes made in JS for a different purpose .gu-transit { opacity: 0.2 !important; diff --git a/csfieldguide/static/interactives/training-ground/scss/training-ground.scss b/csfieldguide/static/interactives/training-ground/scss/training-ground.scss index 41522604c0..c0647651ca 100644 --- a/csfieldguide/static/interactives/training-ground/scss/training-ground.scss +++ b/csfieldguide/static/interactives/training-ground/scss/training-ground.scss @@ -1,4 +1,4 @@ -@import "node_modules/nouislider/distribute/nouislider.css"; +@import "static/interactives/training-ground/node_modules/nouislider/distribute/nouislider"; #interactive-training-ground { max-width: 1000px; diff --git a/csfieldguide/static/svg/csfg-icon-with-text-white.svg b/csfieldguide/static/svg/csfg-icon-with-text-white.svg new file mode 100644 index 0000000000..a7bcb86ca4 --- /dev/null +++ b/csfieldguide/static/svg/csfg-icon-with-text-white.svg @@ -0,0 +1,177 @@ + + + + + + + CSFG icon with title - white + + + + + + + + + + + + + + + + + + + + + + + + + + + CSFG icon with title - white + + + + Computer Science + Field Guide + diff --git a/csfieldguide/static/svg/csfg-icon-with-text.svg b/csfieldguide/static/svg/csfg-icon-with-text.svg new file mode 100644 index 0000000000..3534e0a94b --- /dev/null +++ b/csfieldguide/static/svg/csfg-icon-with-text.svg @@ -0,0 +1,177 @@ + + + + + + + CSFG icon with title + + + + + + + + + + + + + + + + + + + + + + + + + + + CSFG icon with title + + + + Computer Science + Field Guide + diff --git a/csfieldguide/templates/base.html b/csfieldguide/templates/base.html index 8f9b50319f..89a468bf98 100644 --- a/csfieldguide/templates/base.html +++ b/csfieldguide/templates/base.html @@ -32,7 +32,12 @@ {% block css %} {% endblock css %} - + + + {% if PRODUCTION_ENVIRONMENT %} + + + {% endif %} {% block body %} @@ -337,19 +342,6 @@ {% block scripts %} {% endblock scripts %} - - {% if DEPLOYED %} - - - {% endif %} {% endblock body %} diff --git a/docs/_static/img/translation_pipeline_overview.png b/docs/_static/img/translation_pipeline_overview.png deleted file mode 100644 index e0019e2890..0000000000 Binary files a/docs/_static/img/translation_pipeline_overview.png and /dev/null differ diff --git a/docs/author/chapters.rst b/docs/author/chapters.rst index 8639552f06..5235f98079 100644 --- a/docs/author/chapters.rst +++ b/docs/author/chapters.rst @@ -1,7 +1,7 @@ Chapters ############################################################################## -The chapters application (see :ref:`what-is-an-application`) is the main focus of the CS Field Guide website, as it contains the majority of educational material for the project. +The chapters application is the main focus of the Computer Science Field Guide website, as it contains the majority of educational material for the project. .. contents:: Contents :local: @@ -19,7 +19,7 @@ Chapters Content Directory The ``content`` directory for the chapters application contains -- a directory for each language in which content exists, named using the Django locale code. +- a directory for each language in which content exists, named using the Django locale code. This directory contains content Markdown files. - a special ``structure`` directory which contains all configuration YAML files @@ -29,7 +29,7 @@ The ``content`` directory for the chapters application contains Content Files ============================================================================== -There are 2 different types of files used for adding content to the CS Field Guide: +There are 2 different types of files used for adding content to the Computer Science Field Guide: - Content Markdown files - YAML configuration files @@ -61,9 +61,9 @@ In the following sections, each configuration file is explained in more detail. .. note:: - - Some of the keys (:ref:`what-is-a-key`) have angle brackets around them, ````. + - Some of the slugs have angle brackets around them, ````. This means that they are variables and you can call them whatever you like in your configuration file (without the angle brackets). - Key names should be consistent, i.e every instance of should be replaced with the exact same key. + Key names should be consistent, i.e every instance of should be replaced with the exact same slug. .. _application-structure-file: @@ -78,11 +78,11 @@ Application Structure Configuration File - **Required Fields:** - - ``chapters:`` A dictionary of chapters, where each key is a chapter. + - ``chapters:`` A dictionary of chapters, where each slug is a chapter. - **Required Fields:** - - ``:`` The key for a chapter. + - ``:`` The slug for a chapter. - **Required Fields:** @@ -107,9 +107,9 @@ A complete chapter application structure file with multiple chapters may look li Chapter Configuration File ------------------------------------------------------------------------------ -- **File Name:** ``.yaml`` +- **File Name:** ``.yaml`` -- **Location:** ``chapters/content/structure//`` +- **Location:** ``chapters/content/structure//`` - **Referenced in:** ``chapters/content/structure/structure.yaml`` @@ -138,15 +138,15 @@ Chapter Sections Configuration File - **File Name:** ``sections.yaml`` -- **Location:** ``chapters/content/structure//sections/`` +- **Location:** ``chapters/content/structure//sections/`` -- **Referenced in:** ``chapters/content/structure//.yaml`` +- **Referenced in:** ``chapters/content/structure//.yaml`` - **Purpose:** Specifiy sections for a chapter and their relative order. - **Required Fields:** - - ``:`` Key for the section. + - ``:`` Key for the section. - **Required Fields:** diff --git a/docs/author/content_style_guide.rst b/docs/author/content_style_guide.rst index 0c9094c5c4..7d58b21f08 100644 --- a/docs/author/content_style_guide.rst +++ b/docs/author/content_style_guide.rst @@ -4,47 +4,8 @@ Content Style Guide .. contents:: Contents :local: -Most Importantly -============================================================================== - -**Be consistent**. -If you are unsure of how to do something, see if there are similar examples in the Field Guide and follow the style used. -Please get in touch if you find inconsistencies or something doesn't make sense. - -Writing Style -============================================================================== - -Content ------------------------------------------------------------------------------- - -- When using pronouns in reference to a hypothetical person, gender neutral pronouns (they/their/them) should be used. -- All documents (other than those for internal use only) must be written clearly and simply so that a student is able to understand them. -- Any jargon used needs to be clearly explained and should be considered as a glossary definition. - -Separators ------------------------------------------------------------------------------- - -- Use a hyphen to hyphenate words (e.g. ``double-barrelled words``). -- Use ``–`` to add supplemental information (e.g. ``do this – it does something!``). -- ``–`` does not work for titles, so if needed use a hyphen. - -English Spelling ------------------------------------------------------------------------------- - -- Use New Zealand English; this is almost always British English. -- For specific examples check the `UCCSER spelling guide `__. - -Capitalisation Rules -============================================================================== - -- Capitalise every word in a major title, such as a chapter title. -- Capitalise only the first word per sentence in a lesser title, such as a chapter section title or heading (for this purpose a colon or hyphen counts as the end of a sentence). -- Capitalise acronyms/initialisms like *NASA* and *CSFG*. -- Capitalise proper nouns (such as peoples' names) appropriately. -- Do not capitalise general terms or jargon unless the above rules apply. - -Extra notes for specific content -============================================================================== +These notes are specific to the Computer Science Field Guide project. +Be sure to read our `general content style guide `_. Glossary ------------------------------------------------------------------------------ diff --git a/docs/author/curriculum_guides.rst b/docs/author/curriculum_guides.rst index 8b3462aef1..2c0fb2627b 100644 --- a/docs/author/curriculum_guides.rst +++ b/docs/author/curriculum_guides.rst @@ -1,7 +1,7 @@ Curriculum Guides ############################################################################## -The curriculum guides application (see :ref:`what-is-an-application`) contains teacher guides for incorporating Field Guide material into lessons for particular curricula. +The curriculum guides application contains teacher guides for incorporating Field Guide material into lessons for particular curricula. The infrastructure is near-identical to that of the :doc:`./chapters` application, so this page will mostly cover what is different. .. contents:: Contents diff --git a/docs/author/index.rst b/docs/author/index.rst index 5870dfd374..2b9bb638a5 100644 --- a/docs/author/index.rst +++ b/docs/author/index.rst @@ -1,7 +1,7 @@ Author Documentation ############################################################################## -The following pages are for those wanting to write or edit CS Field Guide content. +The following pages are for those wanting to write or edit Computer Science Field Guide content. .. toctree:: :maxdepth: 1 diff --git a/docs/author/translations.rst b/docs/author/translations.rst index 849d46e5ee..4f0ccb5180 100644 --- a/docs/author/translations.rst +++ b/docs/author/translations.rst @@ -6,21 +6,16 @@ Translations Getting Started ============================================================================== -It's really easy to start contributing translations using the CS Field Guide +It's really easy to start contributing translations using the Computer Science Field Guide 1. Read this documentation page, especially the `Translation Notes`_ section. 2. Create an account on `Crowdin `__. -3. Visit the `CS Field Guide Crowdin page `__. +3. Visit the `Computer Science Field Guide Crowdin page `__. 4. Start translating! -.. note:: - - The in-context translation has been removed temporarily as translation infrastructure is being updated. - We aim to `re-add this feature in a future update `__. - Crowdin Overview ============================================================================== -We use a localisation management platform called `Crowdin `__ for translation of the CS Field Guide. +We use a localisation management platform called `Crowdin `__ for translation of the Computer Science Field Guide. Our project is public, meaning that anyone can create an account and contribute translations. Crowdin has excellent documentation for translators, and all translators should read the following documents: @@ -30,7 +25,7 @@ Crowdin has excellent documentation for translators, and all translators should Translation Phases ============================================================================== -There are 3 translation phases used to ensure high quality translation of CS Field Guide content: +There are 3 translation phases used to ensure high quality translation of Computer Science Field Guide content: 1. Translation 2. Proofread @@ -45,7 +40,7 @@ To request to become a proofreader, please `contact `__ +3.12.3 +============================================================================== + +**Release date:** 29th October 2022 + +**Changelog:** + +- Add abiltiy to hide pixel colour codes in pixel-viewer interactive via URL parameter. +- Fix bug where imported package CSS files were not imported. +- Fix bug where pixel-viewer interactive isn't sized correctly when embedded via iframe. +- Replaced deprecation method in matrix-simplifier interactive. +- Update analytics to Plausible. +- Rewrite documentation to project specific content, and linking to general UCCSER documentation where required. +- Display white favicon when browser dark theme is used. `#1957 `__ +- Add project logo variants with text. +- Core dependency changes: + + - Update autoprefixer from 10.4.12 to 10.4.13. + - Update crowdin/github-action from 1.4.15 to 1.4.16. + - Update cssselect from 1.1.0 to 1.2.0. + - Update django from 3.2.15 to 3.2.16. + - Update psycopg2 from 2.9.4 to 2.9.5. + +- Interactive scene-editor dependency changes: + + - Update three from 0.145.0 to 0.146.0. + 3.12.2 ============================================================================== @@ -972,7 +999,7 @@ A configuration tool for the sorting boxes interactive has been added, allowing **Changelog:** -- Rebuild the CS Field Guide website to use an open source Django system based off CS Unplugged (`see the GitHub milestone `__). Major features include: +- Rebuild the Computer Science Field Guide website to use an open source Django system based off CS Unplugged (`see the GitHub milestone `__). Major features include: - Greatly improved translation features. - Allowing student and teacher pages to use the same URLs (switch between modes available in page footer). diff --git a/docs/conf.py b/docs/conf.py index 21a9818790..ba2e7c03c6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# CS Field Guide documentation build configuration file, created by +# Computer Science Field Guide documentation build configuration file, created by # sphinx-quickstart on Sat Jun 10 13:51:35 2017. # # This file is execfile()d with the current directory set to its @@ -48,7 +48,7 @@ master_doc = 'index' # General information about the project. -project = 'CS Field Guide' +project = 'Computer Science Field Guide' copyright = '2017 University of Canterbury Computer Science Education Research Group' author = 'University of Canterbury Computer Science Education Research Group' @@ -131,38 +131,5 @@ # 'figure_align': 'htbp', } -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'CSFieldGuide.tex', 'CS Field Guide Documentation', - 'Jack Morgan, Hayley van Waas', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'csfieldguide', 'CS Field Guide Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'CSFieldGuide', 'CS Field Guide Documentation', - author, 'CSFieldGuide', 'One line description of project.', - 'Miscellaneous'), -] - - - - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/docs/developer/appendices.rst b/docs/developer/appendices.rst index 510098ce66..0afd2a4dbf 100644 --- a/docs/developer/appendices.rst +++ b/docs/developer/appendices.rst @@ -1,7 +1,7 @@ Appendices Application ############################################################################## -The appendices application manages and serves basic pages for the CS Field Guide website, including (but not limited to): +The appendices application manages and serves basic pages for the Computer Science Field Guide website, including (but not limited to): - About page - Contributors diff --git a/docs/developer/chapters.rst b/docs/developer/chapters.rst index e3816d7da3..2a4d18d5c1 100644 --- a/docs/developer/chapters.rst +++ b/docs/developer/chapters.rst @@ -1,7 +1,7 @@ Chapters Application ############################################################################## -The chapters application is the main focus of the CS Field Guide website, as it contains the majority of educational material for the project. +The chapters application is the main focus of the Computer Science Field Guide website, as it contains the majority of educational material for the project. .. note:: diff --git a/docs/developer/deployment.rst b/docs/developer/deployment.rst deleted file mode 100644 index de16a20d5b..0000000000 --- a/docs/developer/deployment.rst +++ /dev/null @@ -1,115 +0,0 @@ -Deployment -############################################################################## - -.. note:: - - This page is intended only for staff within the University of Canterbury - Computer Science Education Research Group, as deployment requires access - to secret passwords and values stored within our private password management - system. - -Requirements -============================================================================== - -The project is designed to run on the following systems: - -- Google App Engine: Flexible Enviroment. -- Google Cloud SQL: Postgres Database. - - - Several Django models require Postgres specific data types, so the - system will not function on a different database type (for example: MySQL). - -- Static files server. - -Deployment overview -============================================================================== - -Deployment requires three steps, and can be done in any order: - -1. Updating static files on Google Cloud Storage Bucket. -2. Updating Django application on Google App Engine. -3. Connecting to the Google Cloud SQL database and updating schema and data. - -We update in the order above to have minimal downtime between deploying a new application and updating the database (currently around 30 to 60 seconds on development deployment). - -Development deployment -============================================================================== - -Deployment of the ``develop`` branch occurs automatically with new commits to the ``develop`` branch, and is deployed by Travis CI. - -The system is deployed to: https://cs-field-guide-dev.appspot.com/. - -The script and files used for deployment is stored in the ``infrastructure/dev-deploy/`` directory. -The ``deploy-app.sh`` script contains descriptions of the process required for deployment. -The file ``dev-deploy-secrets.tar.enc`` is an encrypted archive of files containing sensitive data, and is decrypted by Travis CI. - -Production deployment -============================================================================== - -Deployment of the ``master`` branch occurs automatically with new commits to the ``master`` branch, and is deployed by Travis CI. - -The system is deployed to: https://www.csfieldguide.org.nz/. - -Manual deployment -============================================================================== - -.. warning:: - - The following steps will allow manual deployment. - This information is not exhaustive, but will provide enough information for manual deployment. - The deployment scripts have greater details of the deployment process. - -For any manual deployment, you will require the `gcloud`_ tool to be installed on your machine, and login with the research group admin Google account. - -Manual deployment requires three steps, and can be done in any order: - -1. Updating static files on Google Cloud Storage Bucket. -2. Updating Django application on Google App Engine. -3. Connecting to the Google Cloud SQL database and updating schema and data. - -**Updating static files** - -The simpliest way to upload the static files on the storage bucket, is to do the following: - -1. Delete the following folders if they exist: - - - ``csfieldguide/build/`` - - ``csfieldguide/staticfiles/`` - - ``csfieldguide/temp/`` - - This may require administrator (``sudo``) permissions as these folders are created by Docker. - -2. Run the ``./csfg start`` command. - When the system is started, the static files are generated. - Once the system has started successfully, run the ``./csfg end`` command. - -3. From the root directory, run the following command: - - .. code-block:: bash - - $ gsutil rsync -R csfieldguide/staticfiles/ gs://cs-field-guide-develop/static/ - -**Updating Django application** - -In the ``infrastructure`` directory, create a copy of ``app-sample.yaml`` called ``app.yaml`` in the root directory, and enter the required values. -The complete contents for this file is also stored in our password management system. - -From the root directory, run the following command: - -.. code-block:: bash - - $ gcloud app deploy app.yaml - - -**Updating database** - -To update the development database, we will setup a SQL proxy to the server, and then locally run the Django project that will connect to the server. -We can then perform the ``migrate`` and ``update_data`` commands as required. - -Using the `guide for Django on Google App Engine Flexible Environment`_, download and setup the SQL proxy. -You will need to choose a port that the SQL proxy and Django will operate on, using ``5432`` should work for most developers. -Alter the Django configuration to connect using the proxy port, and run the system. -You should be able to then perform the ``migrate`` and ``update_data`` commands. - -.. _gcloud: https://cloud.google.com/sdk/gcloud/ -.. _guide for Django on Google App Engine Flexible Environment: https://cloud.google.com/python/django/flexible-environment diff --git a/docs/developer/developer_philosophy.rst b/docs/developer/developer_philosophy.rst index c838ec7673..3fc4d1b58b 100644 --- a/docs/developer/developer_philosophy.rst +++ b/docs/developer/developer_philosophy.rst @@ -1,13 +1,13 @@ Developer Philosophy ############################################################################## -We follow the following philosophy for developing the CS Field Guide project: +We follow the following philosophy for developing the Computer Science Field Guide project: - We aim to create software that enables authors to easily create, modify, and share education material for the CS Field Guide project. + We aim to create software that enables authors to easily create, modify, and share education material for the Computer Science Field Guide project. In short: *Think of the author*. -This page explains design decisions we made throughout developing the CS Field Guide system. +This page explains design decisions we made throughout developing the Computer Science Field Guide system. Configuration Files ============================================================================== diff --git a/docs/developer/django_setup.rst b/docs/developer/django_setup.rst index ec399cce37..52e3ed14e0 100644 --- a/docs/developer/django_setup.rst +++ b/docs/developer/django_setup.rst @@ -29,7 +29,7 @@ The following image shows the relationships between models across all applicatio .. image:: ../_static/img/database_overview_diagram.png :alt: A diagram detailing the general structure of the database -The rest of the :doc:`index` will inform you of how to develop the applications and other components of the CS Field Guide project. +The rest of the :doc:`index` will inform you of how to develop the applications and other components of the Computer Science Field Guide project. Loaders ============================================================================== diff --git a/docs/developer/general.rst b/docs/developer/general.rst index 3456b273ea..2c42126621 100644 --- a/docs/developer/general.rst +++ b/docs/developer/general.rst @@ -1,6 +1,6 @@ General Application ############################################################################## -The general application manages and serves basic pages for the CS Field Guide website, including (but not limited to): +The general application manages and serves basic pages for the Computer Science Field Guide website, including (but not limited to): - Homepage diff --git a/docs/developer/index.rst b/docs/developer/index.rst index 12dba1a694..6bd54f56d7 100644 --- a/docs/developer/index.rst +++ b/docs/developer/index.rst @@ -1,7 +1,7 @@ Developer Documentation ############################################################################## -The following pages are for those wanting to develop the CS Field Guide system. +The following pages are for those wanting to develop the Computer Science Field Guide system. .. toctree:: :maxdepth: 1 @@ -16,7 +16,4 @@ The following pages are for those wanting to develop the CS Field Guide system. curriculum_guides interactives static_files - deployment test_suite - translation - translation_infrastructure diff --git a/docs/developer/interactives.rst b/docs/developer/interactives.rst index 2d6b55208f..13239b6317 100644 --- a/docs/developer/interactives.rst +++ b/docs/developer/interactives.rst @@ -147,7 +147,7 @@ A completed interactive requires the following to be included into the repositor - A ``README.md`` file explaining the interactive, linking to any documentation or websites that future developers may find useful. Uninteractives generally don't have a ``README.md`` file unless future developers may find it useful. -- Extra libraries/scripts that have been used have been used and attributed correctly, see :ref:`licence-files`. +- Extra libraries/scripts that have been used have been used and attributed correctly. - Be easily accessible on desktop and mobile, or show a disclaimer that it is suited for desktop use only. - Abides by the repository contribution style guidelines. - Must work in browsers updated within the last year. diff --git a/docs/developer/static_files.rst b/docs/developer/static_files.rst index 8ee16e5f70..bae2d6825e 100644 --- a/docs/developer/static_files.rst +++ b/docs/developer/static_files.rst @@ -6,13 +6,13 @@ Static Files The static files (images, CSS, JavaScript, etc) used within the website go through the following steps: 1. Files are stored within the ``static`` directory. -2. Files are processed with a Gulpfile into the ``build`` directory with ``./csfg dev static`` or ``./csfg dev static_prod``. -3. Files are collected into the ``staticfiles`` directory with ``./csfg dev collect_static``. +2. Files are processed with a Gulpfile into the ``build`` directory with ``./dev static`` or ``./dev static_prod``. +3. Files are collected into the ``staticfiles`` directory with ``./dev collect_static``. -Note that files under the ``static/`` folder are edited and the files under the ``staticfiles/`` folder are generated and should not be edited. -Every interactive and uninteractive has a generated thumbnail stored in ``staticfiles/img/interactives/thumbnails/``. -These can be created with ``./csfg make_interactive_thumbnails``. -You will need to run the ``./csfg collect_static`` command after for them to appear in the ``staticfiles/`` directory. +Note that files under the ``static/`` folder are editable and the files under the ``staticfiles/`` folder are generated and should not be edited. +Every interactive has a generated thumbnail stored in ``staticfiles/img/interactives/thumbnails/``. +These can be created with ``./dev make_interactive_thumbnails``. +You will need to run the ``./dev collect_static`` command after for them to appear in the ``staticfiles/`` directory. JavaScript Files ============================================================================== @@ -26,7 +26,18 @@ If you wish to not apply optimisation steps (`Browserify `_ enables the use of gettext() in JavaScript files to translate text. The JavaScript translation files are prepared before server start. + +Node dependencies +============================================================================== + +Multiple sets of Node dependencies are installed throughout the project using ``package.json`` files. +This includes a high level ``package.json`` file for website dependencies at ``csfieldguide/``, and then more ``package.json`` files within the ``csfieldguide/static/interactives/`` directory. + +We have chosen to install Node dependencies within the Docker container, however we have the installed dependencies excluded from the Docker Compose volume that maps the developer's local directory within the container. + +Each separate ``node_modules`` is specified individually (within ``docker-compose.local.yml`` and ``infrastructure/local/django/Dockerfile``), as the Docker volume of the website dependencies (would be ``csfieldguide/node_modules``) would hide the ``node_modules`` directory for each interactive's dependencies, therefore resulting in interactives looking at the top level ``node_modules`` directory for dependencies.` +This meant that some interactives were using versions on dependencies that they were not intended for. diff --git a/docs/developer/test_suite.rst b/docs/developer/test_suite.rst index 6b65d774a1..95ee8e79c3 100644 --- a/docs/developer/test_suite.rst +++ b/docs/developer/test_suite.rst @@ -8,47 +8,13 @@ Test Suite Running the Test Suite ============================================================================== -``./csfg test_suite`` will run the entire test suite. -For running specific tests, viewing code coverage, and more testing commands, see :doc:`../getting_started/helper_commands`. +``./dev test_suite`` will run the entire test suite. +``./dev test_specific `` will run a specific module of tests, for example, ``./dev test_specific tests.appendices.views`` will run all the views test for appendices. -Structure -============================================================================== +All tests are in the ``csfieldguide/tests/`` directory, which mirrors the structure of the ``csfieldguide/`` directory with directories matching the installed Django applications. -All tests are in the ``tests/`` directory, which in the ``csfieldguide/`` directory (at the same level as the apps). -It is structured as follows: - -.. code-block:: none - - └── tests/ - ├── appendices/ - │   ├── urls/ - │   └── views/ - ├── chapters/ - │   ├── loaders/ - │   ├── management/ - │   ├── models/ - │   ├── urls/ - │   ├── views/ - │   └── ChaptersTestDataGenerator.py - ├── general/ - │   ├── management/ - │   ├── urls/ - │   └── views/ - ├── interactives/ - │   ├── loaders/ - │   │   └── assets/ - │   ├── management/ - │   ├── models/ - │   ├── urls/ - │   ├── utils/ - │   ├── views/ - │   └── InteractivesTestDataGenerator.py - ├── utils - │ └── errors/ - └── BaseTestWithDB.py - -Note that each app being tested has it's own folder, and this is then broken down further into the component being tested (i.e. views, urls, models, etc). +Note that each application being tested has it's own folder, and this is then broken down further into the component being tested (i.e. views, urls, models, etc). Items of interest from this diagram: @@ -72,13 +38,12 @@ Items of interest from this diagram: Adding Tests ============================================================================== -When writing a new test function, it is important that the method name is as descriptive as possible. +When writing a new test function, it is important that the method name is as descriptive as possible. The method name should also be prefixed with ``test_`` as the test suite will only execute methods with this prefix. .. note:: We use `Codecov`_ to check the coverage of our tests. - Every Pull Request should cover 100% of the difference (therefore increasing coverage), Travis will fail if this is not the case. - + Ideally each pull request should cover 100% of the changes (therefore increasing the total project coverage). .. _Codecov: https://codecov.io/ diff --git a/docs/developer/translation.rst b/docs/developer/translation.rst deleted file mode 100644 index 2780fb9ce5..0000000000 --- a/docs/developer/translation.rst +++ /dev/null @@ -1,134 +0,0 @@ -Translation -############################################################################## - - -Translation Principles -============================================================================= - -The following principles were used to guide the design of a translation system for CS Field Guide: - -1. Translations should be 'first class citizens' - they should exist as independent entities from the source content, and be coupled as loosely as possible to it. -2. Translated content should remain accessible even if the source material changes, and an updated translation is not yet available. -3. Users should be able to see all content that exists, even if it is not available in their language. -4. Translated content should be presented solely in the users language, without being interspersed with English. - - -Translatable Files -============================================================================= -Translatable content is stored in three types of files: - -- Markdown files, for content to be processed by Verto. -- Python code. -- HTML templates. -- JavaScript code. - -Markdown files are stored inside the directory tree for a given language (ie. the directory named using the Django locale code). - -For the other three type of files, Django's built-in `translation support `_ is utilised to handle translatable strings. -In Python code, text is wrapped in a ``ugettext`` function call (usually aliased to ``_``). -In HTML templates, text is wrapped in ``{% trans %}``/``{% blocktrans %}`` tags. -In JavaScript code, text is wrapped in a ``gettext`` function call. - - -Sometimes there may be a sentence that will need to be worded differently depending on the value of a variable. -In HTML templates, the Django ``blocktrans`` tag provides for pluralisation. -An example is shown below. - -.. code-block:: html - - {% blocktrans count variable as variable_name %} - The video has been viewed {{ variable_name }} time - {% plural %} - The video has been viewed {{ variable_name }} times - {% endblocktrans %} - -`Django documentation for using the plural tag is here`_. - - -Django provides two different functions for handling pluralisation in JavaScript. -If the variable value is not included in the sentence you can simply use Django's ``ngettext`` function. -However if the variable value `is` included in the sentence you will need to use both Django's ``ngettext`` function and Django's ``interpolate`` function. - - -For example, in the binary cards interactive the user can flip cards to show a number of dots. -In the interactive we tell the user how many dots are showing, if there is only one dot showing we would like to display "1 dot is visible", otherwise display the plural version with the number of dots showing. -To achieve this we use the following syntax, where ``dot_count`` is the number of dots showing. - -.. code-block:: javascript - - var format = ngettext('1 dot is visible', '%(dot_count)s dots are visible', dotCount); - var dotCountText = interpolate(format, {"dot_count": dotCount}, true); - -Django provides further documentation on these functions and `translations in JavaScript here`_. - - -Translatable Model -============================================================================= - -The ``TranslatableModel`` class is a base model class that allows content to be stored using the above principles. -It is availabe in the file ``utils/TranslatableModel.py`` and should be subclassed by all models which contain any user-facing content. - -Django Package - ``modeltranslation`` -****************************************************************************** -The Django modeltranslation package is utilised to stored translated content on a model. -The basic idea is that for each translatable field, an extra database column is added for every language defined in the Django settings file. -When the base field is accessed, ``modeltranslation`` performs some magic to retrieve the translation for the users language. - - -To register translation fields for a given TranslatableModel, add a TranslationOptions subclass to the ``translations.py`` file in the relevant application. -For more details, see the models already registered, or read the `modeltranslation docs `_. - -.. note:: - - The default behaviour for ``modeltranslation`` is to fallback to the English value if no translation is present. - In CS field Guide, this is desirable for text fields such as name and title, but is often undesirable for most other fields (see `Translation Principles`_). - - To disable fallback for a given field: - - - Add ``: None`` to the ``fallback_undefined`` dictionary in the models ``TranslationOptions`` subclass. - - Add ``default=""`` option to the field in it's ``models.py`` definition. - - -Available Languages -****************************************************************************** - -The ``TranslatableModel`` base class includes a mechanism to determine whether a model sufficiently translated and available in a given language. - -This mechanism consists of - -- The ``languages`` field, which is an array field storing the Django language codes for languages in which the model is available. -- The ``translation_available`` property, which returns true if the model is available in the current language. - -When creating the ``TranslatableModel`` instance, the list of available languages should be determined. -This will likely be decided using a list of required fields, where the presence of translations for all required fields leads to the model being marked as available. -The `TranslatableModelLoader `_ base class includes functions to assist with this task. - -In view and template code, the ``translation_available`` property can be checked to determine the presentation of translated content (or lack thereof) on the front end. - - -.. _TranslatableModelLoader: - -Translatable Model Loader -============================================================================= - -The ``TranslatabaleModelLoader`` base class should be subclassed by all loaders that deal with translatable models. -It provides a number of helper functions for dealing with translated content. -It is availabe in the file ``utils/TranslatableModelLoader.py``. - -.. _UtilityFunctions: - -Utility Functions -****************************************************************************** - -The following utility functions are available: - -- ``get_yaml_translations`` - Load translations for model fields from a given YAML file. -- ``get_markdown_translations`` - Load translations for a given Markdown file. -- ``populate_translations`` - Populate translation fields on a model using values in a given dictionary. -- ``mark_translation_availability`` - Modify ``languages`` field to contain all languages for which all required translation fields are populated. - -Refer to the function docstrings for more detailed documentation. -It may also be useful to refer to existing loader implementations to understand how these functions can be used. - -.. _translations in JavaScript here: https://docs.djangoproject.com/en/1.11/topics/i18n/translation/#using-the-javascript-translation-catalog -.. _Django documentation for using the plural tag is here: https://docs.djangoproject.com/en/1.11/topics/i18n/translation/#blocktrans-template-tag diff --git a/docs/developer/translation_infrastructure.rst b/docs/developer/translation_infrastructure.rst deleted file mode 100644 index d4f137f37f..0000000000 --- a/docs/developer/translation_infrastructure.rst +++ /dev/null @@ -1,55 +0,0 @@ -Translation Infrastructure -############################################################################## - -.. note:: - - The in-context translation has been removed temporarily as translation infrastructure is being updated. - We aim to `re-add this feature in a future update `__. - -Crowdin -============================================================================== -We use a localisation management platform called `Crowdin `_ for translation of CS Field Guide. -The project is public, meaning that anyone can create an account and contribute translations. - -Translatable Files -============================================================================== -There are 4 types of files that contain translatable content: - -- Content Markdown files -- HTML templates -- JavaScript code -- ``django.po`` file containing translatable system strings - -Content Markdown source files must always reside under an ``en`` directory tree. -Translated files are downloaded into a directory named with the language's locale code, and with the same structure as the source tree. - -.. note:: - - The locale code differs from the language code in format - where a language code is of form ``ab-cd``, the locale code will be ``ab_CD``. - Directories must be named using the locale code recognised by django for that language. - - For more information, see - - - https://docs.djangoproject.com/en/1.11/topics/i18n/ - - https://github.com/django/django/tree/master/django/conf/locale - - https://github.com/django/django/blob/master/django/utils/translation/trans_real.py#L59 - -The configuration specifying which files should be uploaded for translation is stored in the file ``.arnold.yaml`` in the repository root. -Details about the structure of this file are available within the `Arnold repository `__. - -Review Process -============================================================================== -For a translation of any given string to make it to production release, it must pass the following stages of review: - -1. (Crowdin) Translation Proofread - Review by a second translator with 'proofreader' status in the target language. -2. (GitHub) Technical Review - Review by a member of the CS Field Guide technical team to catch technical errors (i.e. with Verto tags, links, Markdown syntax etc). - Automated testing on travis will also occur at this stage. - -Translation Pipeline -============================================================================== - -The translation pipeline is implemented by the `Arnold repository `__. -The following diagram gives a broad overview of the translation pipeline. -The blue arrows indicate the path from a source file change through to the release of the translation for that change. - -.. image:: ../_static/img/translation_pipeline_overview.png diff --git a/docs/developer/website_design.rst b/docs/developer/website_design.rst index 835fd7ae5e..c86cd50944 100644 --- a/docs/developer/website_design.rst +++ b/docs/developer/website_design.rst @@ -1,7 +1,7 @@ Website Design (HTML templates/CSS) ############################################################################## -This page covers the HTML templates and CSS styling used for the CS Field Guide website. +This page covers the HTML templates and CSS styling used for the Computer Science Field Guide website. In summary: diff --git a/docs/getting_started/code_of_conduct.rst b/docs/getting_started/code_of_conduct.rst deleted file mode 100644 index 1c34b42f83..0000000000 --- a/docs/getting_started/code_of_conduct.rst +++ /dev/null @@ -1,58 +0,0 @@ -Code of Conduct -############################################################################## - -Our Pledge -============================================================================== - -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. - -Our Standards -============================================================================== - -Examples of behavior that contributes to creating a positive environment include: - -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -- The use of sexualized language or imagery and unwelcome sexual attention or advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting - -Our Responsibilities -============================================================================== - -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. - -Scope -============================================================================== - -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. -Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. -Representation of a project may be further defined and clarified by project maintainers. - -Enforcement -============================================================================== - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `csse-education-research@canterbury.ac.nz`. -All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. -The project team is obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. - -Attribution -============================================================================== - -This Code of Conduct is adapted from the `Contributor Covenant`_, `version 1.4`_. - -.. _version 1.4: http://contributor-covenant.org/version/1/4/ -.. _Contributor Covenant: http://contributor-covenant.org/ diff --git a/docs/getting_started/contributing_guide.rst b/docs/getting_started/contributing_guide.rst deleted file mode 100644 index 244e6b4e0c..0000000000 --- a/docs/getting_started/contributing_guide.rst +++ /dev/null @@ -1,198 +0,0 @@ -Contributing Guide -############################################################################## - -Welcome to the Computer Science Field Guide (CSFG) developer community! -We have spent many years creating the CSFG, and we would love for you to get involved into making this guide as great as possible! - -This page lists a set of guidelines for contributing to the project. -These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request. - -As a contributor, you agree to uphold our :doc:`code_of_conduct`. - -.. contents:: Contents - :local: - -Reporting Issues and Making Suggestions -============================================================================== - -This section guides you through submitting an issue or making a suggestion for the CS Field Guide project. -Following these guidelines helps maintainers and the community understand your findings. - -Before Submitting an Issue ------------------------------------------------------------------------------- - -- `Search the issue tracker for the issue/suggestion`_ to see if it has already been logged. - If it has, add a comment to the existing issue (even if the issue is closed) instead of opening a new one. - If the issue is closed and you think it is not resolved, please reopen it. - -How do I Submit a Good Issue or Suggestion? ------------------------------------------------------------------------------- - -Issues are tracked in the GitHub issue tracker (if you've never used GitHub issues before, read this `10 minute guide to become a master`_). -When creating an issue, explain the problem and include additional details to help maintainers understand or reproduce the problem: - -For Reporting an Issue -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- **Use a clear and descriptive title** for the issue to identify the problem. -- **Clearly and concisely describe the issue** and provide screenshots if required. -- **Link any related existing issues**. - -If the issue is a code related issue, also include the following: - -- **Describe the exact steps which reproduce the problem** in as many details as possible. - For example, how you were generating a resource. - When listing steps, **don't just say what you did, explain how you did it**. -- **Explain which behavior you expected to see instead and why.** -- **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. -- **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. -- **Include screenshots or animated GIFs** if it helps explain the issue you encountered. -- **What's the name and version of the OS you're using?** -- **What's the name and version of the browser you're using?** -- **If the problem is related to performance**, please provide specifications of your computer. - -For Making a Suggestion -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Explain the suggestion and include additional details to help maintainers understand the suggestion: - -- **Use a clear and descriptive title** for the issue to identify the suggestion. -- **Clearly and concisely describe the suggestion** and provide screenshots if required. -- **Explain why this suggestion would be useful** to most CS Field Guide users and isn't something that should be a implemented as a community variant of the project. -- **Link any related existing suggestions**. - -.. note:: - - **Internal Staff Only:** Assigning Issues - - Our policy is to only assign a person to an issue when they are actively working on the issue. - Please don't assign yourself when you *plan* to do the task (for example: in the next few days), assign yourself when you begin work. - This allows other team members to clearly see which tasks are available to be worked on. - -Your First Code Contribution (pull request) -============================================================================== - -Unsure where to begin contributing to CS Field Guide? -You can start by looking through the `issue tracker`_. - -Pull Requests ------------------------------------------------------------------------------- - -- **Include a detailed explaination** of the proposed change, including screenshots and animated GIFs in your pull request whenever possible. -- **Read and apply the style guides** listed below. -- Your pull request should be on a new branch from our ``develop`` branch, **that is being requested to merge back into** ``develop``. - The naming conventions of branches should be descriptive of the new addition/modification. - Ideally they would specify their namespace as well, for example: - - - ``resource/puzzle-town`` - - ``topic/algorithms`` - - ``issue/234`` - -- Link to any relevant existing issues/suggestions. -- Add necessary documentation (if appropriate). - -We aim to keep the CS Field Guide project as robust as possible, so please do your best to ensure your changes won't break anything! - -Style and Etiquette Guides -============================================================================== - -Git ------------------------------------------------------------------------------- - -- Commits should be as descriptive as possible. - Other developers (and even future you) will thank you for your forethought and verbosity for well documented commits. - Generally: - - - Limit the first line to 72 characters or less - - Reference issues and pull requests liberally - -- We use `Vincent Driessen's Git Branching Model `_ for managing development. - Please read this document to understand our branching methods, and how to perform clear branches and merges. - - Specifically for our respository: - - - We create a new branch for each task of work, no matter how small it is. - - We create the branch off the ``develop`` branch. - - In general, the new branch should begin with ``issue/`` followed by the issue number. - - When a branch is completed, a pull request is created on GitHub for review. - - Branches are merged back into ``develop``. - -GitHub ------------------------------------------------------------------------------- - -.. note:: - - Internal Staff Only - -- Mention a user (using the ``@`` symbol) when an issue is relevant to them. -- Only assign yourself to an issue, when you are actively working on it. -- The technical team may tag an author to review specific pull requests, and as a reviewer you can either approve, request changes, or just leave comments. -- A pull request requires one review approval to be merged. -- If multiple people are tagged as reviewers, we only need one review (unless otherwise specified). - For example: For content changes, we ask that at least one member from each of the content and technical teams reviews the pull request. -- The creator of the pull request should assign all those suitable for review. -- The creator of the pull request is the only person who should merge the pull request. - If you approve a pull request and it shows the big green button, please resist clicking it! - -Project Structure ------------------------------------------------------------------------------- - -- Directories should be all lowercase with dashes for spaces. -- Directories and files should use full words when named, however JavaScript, CSS, and image directories can be named ``js/``, ``css/``, and ``img/`` respectively. - -Text (Markdown) ------------------------------------------------------------------------------- - -- Each sentence should be started on a newline (this greatly improves readability when comparing two states of a document). - -Programming ------------------------------------------------------------------------------- - -Quote from Google style guides: - - Be consistent. - - If you’re editing code, take a few minutes to look at the code around you and determine its style. - If they use spaces around all their arithmetic operators, you should too. - If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too. - - The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. - We present global style rules here so people know the vocabulary, but local style is also important. - If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. - Avoid this. - -We aim to abide by the following style guides: - -- **Python** - We follow `PEP8`_ except for one change of line length. - `Django recommends allowing 119 characters`_, so we use this as our line length limit. - This style is enforced by the `flake8`_ style checker. -- **HTML** - We follow the `open source HTML style guide`_ by @mdo. -- **CSS** - We follow the `open source CSS style guide`_ by @mdo. -- **JavaScript** - We follow the `Google JavaScript style guide`_ with 4 space indentation. - - -.. _licence-files: - -Licencing ------------------------------------------------------------------------------- - -Any third-party libraries or packages used within this project should be listed within the ``LICENCE-THIRD-PARTY`` file, with a full copy of the licence available within the ``third-party-licences`` directory. - -Final Comments -============================================================================== - -After reading the sections above, you should be able to answer the following questions: - -- When do I create a issue and how do I describe it? -- When and how do I create a new Git branch to work on? -- *Internal staff only:* When do I assign myself to an issue? - -.. _Search the issue tracker for the issue/suggestion: https://github.com/uccser/cs-field-guide/issues?utf8=%E2%9C%93&q=is%3Aissue -.. _10 minute guide to become a master: https://guides.github.com/features/issues/ -.. _issue tracker: https://github.com/uccser/cs-field-guide/issues -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ -.. _Django recommends allowing 119 characters: https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/ -.. _open source HTML style guide: http://codeguide.co/#html -.. _open source CSS style guide: http://codeguide.co/#css -.. _Google JavaScript style guide: https://google.github.io/styleguide/javascriptguide.xml -.. _flake8: http://flake8.pycqa.org/en/latest/ diff --git a/docs/getting_started/helper_commands.rst b/docs/getting_started/helper_commands.rst deleted file mode 100644 index 3f75ce7b45..0000000000 --- a/docs/getting_started/helper_commands.rst +++ /dev/null @@ -1,358 +0,0 @@ -Helper Commands for Developing -############################################################################## - -.. note:: - - We assume by this point you have installed the project, checked the setup is working (see :ref:`installation-check-project-setup-works`), and also have a basic understanding of the :doc:`project structure `. - -The CS Field Guide project uses many systems (Django, Docker, Gulp, etc) to run, so we have written a script for running groups of commands for running the system while developing. - -The script is called ``csfg`` and can be found in the ``cs-field-guide`` folder of the repository. -To run this script, open a terminal window in the directory and enter the following command (you don't need to enter the ``$`` character, this shows the start of your terminal prompt): - -.. code-block:: bash - - $ ./csfg [COMMAND] - -Where ``[COMMAND]`` is a word from the list below: - -- :ref:`build` -- :ref:`clean` -- :ref:`collect_static` -- :ref:`compilemessages` -- :ref:`docs` -- :ref:`end` -- :ref:`help` -- :ref:`logs` -- :ref:`make_interactive_thumbnails` -- :ref:`makemessages` -- :ref:`makemigrations` -- :ref:`migrate` -- :ref:`reboot_django` -- :ref:`restart` -- :ref:`restart_build` -- :ref:`shell` -- :ref:`start` -- :ref:`static` -- :ref:`static_prod` -- :ref:`style` -- :ref:`test_backwards` -- :ref:`test_coverage` -- :ref:`test_specific` -- :ref:`test_suite` -- :ref:`update` -- :ref:`update_static` -- :ref:`update_data` -- :ref:`wipe` - -All users of the project (content and technical developers) should become familiar with the following commands: - -- :ref:`start` -- :ref:`end` -- :ref:`build` -- :ref:`update` - ------------------------------------------------------------------------------ - -.. _build: - -``build`` -============================================================================== - -Running ``./csfg build`` will build or rebuild the Docker images that are required for the CS Field Guide system. -When you run this command for the first time it can take roughly 15 to 30 minutes depending on your computer and internet speed. - -Images are only required to be built once, unless the image specifications change. - ------------------------------------------------------------------------------ - -.. _clean: - -``clean`` -============================================================================== - -Running ``./csfg clean`` deletes 'dangling' Docker images left over from builds, which will free up hard drive space. - ------------------------------------------------------------------------------ - -.. _collect_static: - -``collect_static`` -============================================================================== - -Running ``./csfg collect_static`` runs the Django ``collectstatic`` command to collect static files. It will copy files under the ``static/`` folder into the ``staticfiles/`` folder. - ------------------------------------------------------------------------------ - -.. _compilemessages: - -``_compilemessages`` -============================================================================== - -Running ``./csfg _compilemessages`` runs the Django ``compilemessages`` command. This runs over ``.po`` files and creates ``.mo`` files which are optimised for use by ``gettext``. -You will need to run this command after each time you create your message file or each time you make changes to it. - ------------------------------------------------------------------------------ - -.. _docs: - -``docs`` -============================================================================== - -Running ``./csfg docs`` will remove any existing documentation and build a fresh copy of the documentation for the CS Field Guide. - ------------------------------------------------------------------------------ - -.. _end: - -``end`` -============================================================================== - -Running ``./csfg end`` will stop any containers which are currently running, this usually takes 10 to 20 seconds. - ------------------------------------------------------------------------------ - -.. _help: - -``help`` -============================================================================== - -Running ``./csfg help`` displays brief help text for the script. -More details for each command can be found on this page. - ------------------------------------------------------------------------------ - -.. _logs: - -``logs`` -============================================================================== - -Running ``./csfg logs`` will display the logs for the running systems. -The output is for all logs until the time the command was run, therefore successive calls may display new logs. - -To follow logs as they output, enter ``docker compose logs --follow``. - ------------------------------------------------------------------------------ - -.. _make_interactive_thumbnails: - -``make_interactive_thumbnails`` -============================================================================== - -Running ``./csfg make_interactive_thumbnails`` generates the thumbnails for each interactive. -Thumbnails are not generated for uninteractives. -You will need to run the ``./csfg collect_static`` command after for them to appear in the ``staticfiles/`` directory. -The thumbnail for each interactive will be saved under ``staticfiles/img/interactives/thumbnails//.png``. - ------------------------------------------------------------------------------ - -.. _makemessages: - -``makemessages`` -============================================================================== - -Running ``./csfg makemessages`` runs the Djanog ``makemessages`` command. -This will create message files where each message file represents a single language. -Message files contain all available translation strings and how they should be represented in the given language. - ------------------------------------------------------------------------------ - -.. _makemigrations: - -``makemigrations`` -============================================================================== - -Running ``./csfg makemigrations`` runs the Django ``makemigrations`` command to create migration files. - ------------------------------------------------------------------------------ - -.. _migrate: - -``migrate`` -============================================================================== - -Running ``./csfg migrate`` runs the Django ``migrate`` command to apply migration files. - ------------------------------------------------------------------------------ - -.. _reboot_django: - -``reboot_django`` -============================================================================== - -Running ``./csfg reboot_django`` will rebuild the Django Docker container. - ------------------------------------------------------------------------------ - -.. _restart: - -``restart`` -============================================================================== - -Running ``./csfg restart`` is a shortcut for running: - -- ``./csfg end`` -- ``./csfg start`` - -More details for each command can be found on this page. - ------------------------------------------------------------------------------ - -.. _restart_build: - -``restart_build`` -============================================================================== - -Running ``./csfg restart_build`` is a shortcut for running: - -- ``./csfg end`` -- ``./csfg build`` -- ``./csfg start`` - -More details for each command can be found on this page. - ------------------------------------------------------------------------------ - -.. _shell: - -``shell`` -============================================================================== - -Running ``./csfg shell`` opens a bash terminal within the Django container (this requires the CS Field Guide system to be running). - -This is the equivalent to entering ``docker compose run django bash``. - ------------------------------------------------------------------------------ - -.. _start: - -``start`` -============================================================================== - -Running ``./csfg start`` starts the development environment. -If this is the first time you're running this script it may take roughly 15 to 30 minutes, depending on your computer and internet speed. - -Once the development environment is operational, the script will perform the following tasks: - -- Start the Django website system -- Start the Nginx server to display the website and static files -- Start the database server - -Once the script has performed all these tasks, the script will tell you to run the ``update`` command. - ------------------------------------------------------------------------------ - -.. _static: - -``static`` -============================================================================== - -Running ``./csfg static`` runs the commands for generating the static files for the website. - -If changes are made to the static files (for example, a new image is added) when the system is running, this command needs to be entered to view the new files on the website. - ------------------------------------------------------------------------------ - -.. _static_prod: - -``static_prod`` -============================================================================== - -Running ``./csfg static_prod`` runs the commands for generating production static files for the website. -This produces compressed SASS files without sourcemaps. - ------------------------------------------------------------------------------ - -.. _style: - -``style`` -============================================================================== - -Running ``./csfg style`` will run the ``flake8`` and ``pydocstyle`` commands to check the style of the project. -If the output is ``0`` for a check, then there are zero errors. - ------------------------------------------------------------------------------ - -.. _test_backwards: - -``test_backwards`` -============================================================================== - -Running ``./csfg test_backwards`` will run the test suite in reverse. -This is useful to check if any tests are influencing the result of each other. -If this command if run on Travis CI, it will only run for a pull request. - ------------------------------------------------------------------------------ - -.. _test_coverage: - -``test_coverage`` -============================================================================== - -Running ``./csfg test_coverage`` will display a table detailing test code coverage, from the report generated by ``./csfg test``. - ------------------------------------------------------------------------------ - -.. _test_specific: - -``test_specific`` -============================================================================== - -Running ``./csfg test_specific [MODULE_PATH]`` will run a specific test module. -For example, running ``./csfg test_specific tests.resources.views.test_index_view`` will only run the tests for checking the index view of the resources application. - ------------------------------------------------------------------------------ - -.. _test_suite: - -``test_suite`` -============================================================================== - -Running ``./csfg test_suite`` will run the test suite, and create a report detailing test code coverage. -The code coverage report can be displayed by running ``./csfg test_coverage``. - ------------------------------------------------------------------------------ - -.. _update: - -``update`` -============================================================================== - -Running ``./csfg update`` runs the Django ``makemigratations`` and ``migrate`` commands for updating the database schema, and then runs the custom ``update_data`` command to load the chapters content into the database. -It also runs the ``static`` command to generate static files and the ``make_interactive_thumbnails`` command which generates the thumbnails for the interactive links. - -If changes are made to the chapters content when the system is running, this command needs to be run to view the new changes on the website. - ------------------------------------------------------------------------------ - -.. _update_static: - -``update_static`` -============================================================================== - -Running ``./csfg update_static`` updates and collects static files by running the ``./csfg static`` and ``./csfg collect_static`` commands. - ------------------------------------------------------------------------------ - -.. _update_data: - -``update_data`` -============================================================================== - -Running ``./csfg update_data`` runs the custom ``update_data`` command to load the chapters content into the database. - ------------------------------------------------------------------------------ - -.. _wipe: - -``wipe`` -============================================================================== - -Running ``./csfg wipe`` deletes all Docker containers and images on your computer. -Once this command has be run, a full download and rebuild of images is required to run the system (can be triggered by the ``build`` or ``start`` commands). - ------------------------------------------------------------------------------ - -You now know the basic commands for using the CS Field Guide system. -You are now ready to tackle the documentation for the area you wish to contribute on. -Head back to the :doc:`documentation homepage <../index>` and choose the documentation related to the task you wish to contribute to. diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst deleted file mode 100644 index bdd0622ba7..0000000000 --- a/docs/getting_started/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -Getting Started -############################################################################## - -This documentation will help you understand how the project is setup, basic steps on how to use it, and our guidelines for your contributions. - -.. note:: - - This project adheres to the Contributor Covenant code of conduct. - By participating, you are expected to uphold this code. - Please read our :doc:`Code of Conduct ` before continuing. - You can report unacceptable behaviour by `emailing us `_. - -.. toctree:: - :hidden: - - code_of_conduct - -.. toctree:: - :maxdepth: 1 - :caption: Contents - - contributing_guide - installation - project_structure - helper_commands diff --git a/docs/getting_started/installation.rst b/docs/getting_started/installation.rst deleted file mode 100644 index 72310e333a..0000000000 --- a/docs/getting_started/installation.rst +++ /dev/null @@ -1,36 +0,0 @@ -Installation Guide -################################################# - -Please read our `installation guide`_ within our `UCCSER Documentation`_ to set your machine up for working on the CS Field Guide project. - -.. _installation-check-project-setup-works: - -Step 9: Check Project Setup Works -================================================= - -To check the project works, open a terminal in the project root directory, which is the ``cs-field-guide/`` directory (should contain a file called ``dev``). - -Type the following command into the terminal (we cover this command in more detail on the helper commands page): - -.. code-block:: bash - - $ ./dev start - -If this is the first time you're running this script it will need to build system images. -This may take some time (roughly 5 to 30 minutes), depending on your computer and internet speed. - -Once the ``./dev start`` command has completed, you will need to run the update command. -Type the following into your terminal: - - .. code-block:: bash - - $ ./dev update - -You can find information about this command on the helper commands page. - -Once the update command has completed you should then be able to open your preferred web browser to the URL ``cs-field-guide.localhost`` and see the CS Field Guide homepage. - -Congratulations if you made it this far and everything is working, you're all set to contribute to the CS Field Guide project. - -.. _UCCSER Documentation: https://uccser.github.io/ -.. _installation guide: https://uccser.github.io/technical-documentation/installation-guide/ diff --git a/docs/getting_started/project_structure.rst b/docs/getting_started/project_structure.rst deleted file mode 100644 index 7384fa41dd..0000000000 --- a/docs/getting_started/project_structure.rst +++ /dev/null @@ -1,124 +0,0 @@ -Project Structure -########################################### - -This page covers the structure of the CS Field Guide project. -The following diagram will be helpful when reading the following sections: - -.. raw:: html - :file: ../_static/html_snippets/project_directory_tree.html - -Repository Directory -================================================= - -The repository directory (or root directory) contains the following: - -- ``csfieldguide/`` - - - This directory contains the Django web system for the CS Field Guide website. - This includes all raw text content, images, resources, etc. - -- ``docs/`` - - - This directory contains the documentation for the repository (which includes the file you are reading now). - -- ``subtitles/`` - - - This directory contains subtitle files for CS Field Guide videos. - -- ``README.md`` - - - This file contains an introduction and important information for the repository. - -- ``LICENCE`` - - - This file details the MIT licence that covers the project infrastructure. - -- ``LICENCE-CONTENT`` - - - This file details the Creative Commons Attribution-ShareAlike 4.0 International license. - This licence applies to Markdown files located within the ``csfieldguide/chapters/content/`` directory and images under the ``csfieldguide/static/img`` directory. - -- ``LICENCE-THIRD-PARTY`` - - - This file contains summaries of licences for third-party libraries or other resources that may be distributed under licences different than the CS Field Guide licence. - A full copy of their respective licences can be found in the ``third-party-licences`` directory. - -- Plus other files used for installation and repository configuration. - -csfieldguide Directory -================================================= - -The ``csfieldguide/`` directory holds the Django web system and is split across the following directories: - -- ``config/`` - - - This directory holds the settings used by the Django system. - It's unlikely you'll edit the contents of this directory unless you are changing the Django configuration (for example: adding a new application). - -.. _django-applications: - -Django contains 'applications' which are Python packages that provide some set of features. -Each large part/chunk of the CS Field Guide is a separate application. -The project currently contains the following applications: - -- ``general/`` - - - This application contains webpages for generic pages on the website. - For example the homepage. - -- ``chapters/`` - - - The core CS Field Guide content is split into chapters. - -- ``curriculum_guides/`` - - - Curriculum guides help teachers utilise CSFG material for specific curricula. - -- ``interactives/`` - - - This application stores all data related to interactives in the CS Field Guide. - -- ``appendices/`` - - - This application contains minor appendices such as the `about` and `contributors` pages. - It also provides links to other important applications, like Interactives and the Glossary, but does not host any of them. - -Details on how to modify an application can be found within their relavent author and developer documentation pages. - -The following directories are also required by the Django system: - -- ``static/`` - - - This directory contains non-user-generated media assets (for example: images, JavaScript, CSS/SCSS, etc). - -- ``templates/`` - - - This directory contains all the HTML templates for the Django system. - -The following directories are used when the server is running (for example: a script compiles the SCSS to CSS and saves it to the ``build/`` directory for serving on a webpage). -You should never save anything in these directories, as the contents are often overwritten and cleared. - -- ``build/`` - - - Contains the generated output of the front-end script (for example: compiled and minified CSS and JavaScript, compressed images, etc). - -The ``csfieldguide/`` directory also contains the following files: - -- ``gulpfile.js`` - - - This file is where all gulp code belongs. - This file is also where gulp tasks are defined. - -- ``make-interactive-thumbnails.js`` - - - A script for generating interactive thumbnails. - -- ``manage.py`` - - - A file created by Django used to manage the Django web system. - Don't modify the contents of this file. - -- ``package.json`` - - - npm's configuration file for projects and modules. - Here we include any dependencies the project has. diff --git a/docs/index.rst b/docs/index.rst index 2d56f60f41..62ed652395 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,27 +1,32 @@ -Welcome to the CS Field Guide +Computer Science Field Guide Documentation ############################################################################## -Welcome to the documentation for the CS Field Guide project. +Welcome to the documentation for the Computer Science Field Guide project. +This project's documentation expands on the `general UCCSER documentation `_, which contains our contributing guide, installation guides, technical stack explanations, style guides, and much more. + +This documentation contains information specific to the Computer Science Field Guide project. + + + The documentation is split into the following sections: ------------------------------------------------------------------------------ -:doc:`Getting Started Documentation ` +`Getting Started Documentation `_ ============================================================================== This documentation contains: - Our expectations of your contributions to the project -- Steps to install the project on your system +- Steps to install the project on your system for local development - Explainations on how the project is setup -- Details on basic commands to use the system ------------------------------------------------------------------------------ :doc:`Author Documentation ` ============================================================================== -This documentation is for those who want to help write content for the CS Field Guide project, specifically text content. +This documentation is for those who want to help write content for the Computer Science Field Guide project, specifically text content. This is the documentation to read if you want to do any of the following (or similar): - Add a new chapter or chapter section @@ -32,7 +37,7 @@ This is the documentation to read if you want to do any of the following (or sim :doc:`Developer Documentation ` ============================================================================== -This documentation is for those who want to contribute to developing the Django system for delivering the CS Field Guide content. +This documentation is for those who want to contribute to developing the Django system for delivering the Computer Science Field Guide content. This is the documentation to read if you want to do any of the following (or similar): - Edit HTML templates used to render webpages @@ -48,9 +53,8 @@ This is the documentation to read if you want to do any of the following (or sim :maxdepth: 4 :caption: Table of Contents - getting_started/index + Getting Started Documentation author/index developer/index - other/index troubleshooting changelog diff --git a/docs/other/faq.rst b/docs/other/faq.rst deleted file mode 100644 index d99cc385a4..0000000000 --- a/docs/other/faq.rst +++ /dev/null @@ -1,49 +0,0 @@ -Frequently Asked Questions -############################################################################## - -The chapters application is the main focus of the CS Field Guide website, as it contains the majority of educational material for the project. - -.. contents:: Contents - :local: - -.. _what-is-a-key: - -What is a Key? -============================================================================== - -We use the term "key" to specify a field name. -Keys map to particular values (which range from learning outcome text, to the structure and attributes of a lesson). - -A key is a short label for something, containing only letters, numbers, or hyphens. -In our system, a key must be no longer than 50 characters, and use hyphens instead of underscores. - -These are *valid* examples of keys: - -- ``algorithms`` -- ``binary-numbers`` -- ``challenge-2`` - -These are *invalid* examples of keys: - -- ``Algorithms`` -- ``Binary Numbers`` -- ``Binary_Numbers`` -- ``binary_numbers`` -- ``challenge 2`` - -Keys must be exact matches to work, for example, if you name a lesson ``bits-and-bytes``, referencing it in another configuration file as ``bytes-and-bits`` will raise an error. - -See also: - -- `Definition of URL slug on Wikipedia`_ - -.. _what-is-an-application: - -What is an Application? -============================================================================== - -Django contains 'applications' which are Python packages that provide some set of features. -Each large part/chunk of the CS Field Guide is a separate application. -Read :ref:`this section in our project structure guide ` for details of the applications used in the CS Field Guide system. - -.. _Definition of URL slug on Wikipedia: https://en.wikipedia.org/wiki/Semantic_URL#Slug diff --git a/docs/other/index.rst b/docs/other/index.rst deleted file mode 100644 index d910d4b75f..0000000000 --- a/docs/other/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Other Documentation -############################################################################## - -.. toctree:: - :maxdepth: 1 - :caption: Contents - - faq diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 8e55f4ae16..1f6126259c 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -1,23 +1,21 @@ Troubleshooting ############################################################################## -``csfg`` helper script +``dev`` helper script ============================================================================== -I get a ``No such file or directory`` error when running the ``csfg`` script +I get a ``No such file or directory`` error when running the ``dev`` script ------------------------------------------------------------------------------ Check your terminal working directory is within the ``cs-field-guide`` directory, the root directory of the project. -Running the ``ls`` command in this directory should list the ``csfg`` file. +Running the ``ls`` command in this directory should list the ``dev`` file. -I have an error when running ``./csfg start`` +I have an error when running ``./dev start`` ------------------------------------------------------------------------------ -If you are having issues running the ``start`` command, try rebuilding the system images with ``./csfg build``. +If you are having issues running the ``start`` command, try rebuilding the system images with ``./dev build``. Changes may be have been made to the system images since you initally created them. -If this still doesn't solve your problem, you could also try deleting any existing images with ``./csfg wipe``, and then build and start the system with ``./csfg start``. - If issue still persists, log a bug on our `issue tracker`_. Viewing website @@ -30,17 +28,12 @@ Firstly check the image is located in the ``staticfiles/`` directory. If the image isn't located within the directory, check the original image is located within the ``static`` directory. If the image is located within the ``static/`` directory, check the filepath is correct. -When running ``./csfg update``, the script will report an error if an image cannot be found. - -Currently ``./csfg update_static`` removes thumbnail images and is a known issue. -To get them back run ``./csfg update``. +When running ``./dev update``, the script will report an error if an image cannot be found. Changed CSS/SCSS styles are not updated when I view the website ------------------------------------------------------------------------------ -Firstly check the compiled CSS is located in the ``staticfiles/`` directory, and that the changes have appeared in the compiled CSS file. -If the CSS file does not include the changes made, run ``./csfg update_static``. -If you are editing SCSS files, check the ``./csfg static`` command isn't reporting SCSS compilation errors. +Check the logs of the Node container processing the static files with ``./dev logs -f node``. The website isn't displaying when I open ``cs-field-guide.localhost`` in a browser ---------------------------------------------------------------------------------------------- diff --git a/requirements/base.txt b/requirements/base.txt index fdad43798b..a33ee0a327 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -1,5 +1,5 @@ # Django -django==3.2.15 +django==3.2.16 django-environ==0.9.0 django-bootstrap-breadcrumbs==0.9.2 @@ -8,7 +8,7 @@ gunicorn==20.1.0 whitenoise==6.2.0 # Database APIs -psycopg2==2.9.4 +psycopg2==2.9.5 # Images django-inline-svg==0.1.1 @@ -21,7 +21,7 @@ python-markdown-math==0.6 # XML Parsing lxml==4.9.1 -cssselect==1.1.0 +cssselect==1.2.0 # YAML Loading PyYAML==5.4.1