Add documentation GitHub action.

Include documentation for three cobrands.

.github/workflows/coverage.yml

@@ -1,6 +1,10 @@
 name: Coverage
 
-on: [push, pull_request]
+on:
+  push:
+    branches-ignore:
+      - generated-code-docs
+  pull_request:
 
 jobs:
   test:

.github/workflows/cypress.yml

@@ -1,6 +1,10 @@
 name: Cypress
 
-on: [push, pull_request]
+on:
+  push:
+    branches-ignore:
+      - generated-code-docs
+  pull_request:
 
 jobs:
   test:

.github/workflows/default.yml

@@ -1,6 +1,10 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches-ignore:
+      - generated-code-docs
+  pull_request:
 
 jobs:
   test:

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Deploy POD documentation to pages
+
+on:
+  push:
+    branches: ["master", "generated-code-docs"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/cache@v2
+        with:
+          path: ~/perl5
+          key: perl-pod
+      - uses: actions/configure-pages@v2
+      - name: Install packages
+        run: bin/cpanm -l ~/perl5 --quiet --notest Pod::ProjectDocs
+      - name: Generate documentation
+        run: ~/perl5/bin/pod2projdocs -out _site -lib perllib -title fixmystreet -desc 'Code documentation for the FixMyStreet platform' -nosourcecode
+        env:
+          PERL5LIB: /home/runner/perl5/lib/perl5
+      - name: Deploy to GitHub Pages
+        uses: cpina/github-action-push-to-another-repository@main
+        env:
+          SSH_DEPLOY_KEY: ${{ secrets.POD_DEPLOY_KEY }}
+        with:
+          source-directory: '_site'
+          destination-github-username: 'mysociety'
+          destination-repository-name: 'fixmystreet-pod'
+          target-branch: main

perllib/FixMyStreet/Cobrand/Greenwich.pm

@@ -1,19 +1,57 @@
+=head1 NAME
+
+FixMyStreet::Cobrand::Greenwich - code specific to the Greenwich cobrand
+
+=head1 SYNOPSIS
+
+Greenwich use their own Open311 endpoint, backing on to MS Dynamics.
+
+=cut
+
 package FixMyStreet::Cobrand::Greenwich;
 use parent 'FixMyStreet::Cobrand::UKCouncils';
 
 use strict;
 use warnings;
 
+=head2 Defaults
+
+=over 4
+
+=cut
+
 sub council_area_id { return 2493; }
 sub council_area { return 'Royal Borough of Greenwich'; }
 sub council_name { return 'Royal Borough of Greenwich'; }
 sub council_url { return 'greenwich'; }
 
+=item * We use slightly different text on the geocode form.
+
+=cut
+
 sub enter_postcode_text {
     my ($self) = @_;
     return 'Enter a Royal Greenwich postcode, or street name and area';
 }
 
+=item * We only shows 20 reports per page on the map.
+
+=cut
+
+sub reports_per_page { return 20; }
+
+=item * Users with a royalgreenwich.gov.uk email can always be found in the admin.
+
+=cut
+
+sub admin_user_domain { 'royalgreenwich.gov.uk' }
+
+=item * We do not send questionnaires.
+
+=cut
+
+sub send_questionnaires { 0 }
+
 sub disambiguate_location {
     my $self    = shift;
     my $string  = shift;
@@ -32,6 +70,24 @@ sub disambiguate_location {
     };
 }
 
+=head2 pin_colour
+
+Shropshire uses the following pin colours:
+
+=over 4
+
+=item * grey: 'not responsible'
+
+=item * green: fixed or closed
+
+=item * red: confirmed
+
+=item * yellow: any other open state (e.g. 'action scheduled' or 'in progress')
+
+=back
+
+=cut
+
 sub pin_colour {
     my ( $self, $p, $context ) = @_;
     return 'grey' if $p->state eq 'not responsible';
@@ -40,11 +96,13 @@ sub pin_colour {
     return 'yellow';
 }
 
-sub reports_per_page { return 20; }
+=head2 open311_extra_data_include
 
-sub admin_user_domain { 'royalgreenwich.gov.uk' }
+When sending reports via Open311, we include an C<external_id> attribute, set
+to the report ID, and a C<closest_address> attribute set to the already
+looked-up closeest address.
 
-sub send_questionnaires { 0 }
+=cut
 
 sub open311_extra_data_include {
     my ($self, $row, $h) = @_;
@@ -65,6 +123,13 @@ sub open311_extra_data_include {
     return $open311_only;
 }
 
+=head2 open311_contact_meta_override
+
+When fetching services via Open311, make sure some fields are set to
+C<server_set> (they are not asked of the user, but set by the server).
+
+=cut
+
 sub open311_contact_meta_override {
     my ($self, $service, $contact, $meta) = @_;
 
@@ -74,6 +139,13 @@ sub open311_contact_meta_override {
     }
 }
 
+=head2 should_skip_sending_update
+
+If an update was made on a report sent to the old Greenwich Open311 server,
+skip trying to send that update.
+
+=cut
+
 sub should_skip_sending_update {
     my ($self, $update) = @_;
 

perllib/FixMyStreet/Cobrand/Lincolnshire.pm

@@ -1,3 +1,15 @@
+=head1 NAME
+
+FixMyStreet::Cobrand::Lincolnshire - code specific to the Lincolnshire cobrand
+
+=head1 SYNOPSIS
+
+Lincolnshire is a two-tier authority, and uses a Confirm back end.
+
+=head1 DESCRIPTION
+
+=cut
+
 package FixMyStreet::Cobrand::Lincolnshire;
 use parent 'FixMyStreet::Cobrand::Whitelabel';
 
@@ -10,24 +22,71 @@ use Try::Tiny;
 use JSON::MaybeXS;
 
 use Moo;
+
+=pod
+
+Confirm backends expect some extra values and have some maximum lengths
+for certain fields, implemented with a couple of roles.
+
+=cut
+
 with 'FixMyStreet::Roles::ConfirmOpen311';
 with 'FixMyStreet::Roles::ConfirmValidation';
 
+=head2 Defaults
+
+=over 4
+
+=cut
+
 sub council_area_id { return 2232; }
 sub council_area { return 'Lincolnshire'; }
 sub council_name { return 'Lincolnshire County Council'; }
 sub council_url { return 'lincolnshire'; }
+
+=item * Lincolnshire is a two-tier authority
+
+=cut
+
 sub is_two_tier { 1 }
 
+=item * Lincolnshire's /around map shows only open reports by default.
+
+=cut
+
 sub on_map_default_status { 'open' }
 
+=item * We do not send questionnaires.
+
+=cut
+
 sub send_questionnaires { 0 }
+
+=item * We include the C<external_id> (Confirm reference) in the acknowledgement email.
+
+=cut
+
 sub report_sent_confirmation_email { 'external_id' }
 
+=item * Users with a lincolnshire.gov.uk email can always be found in the admin.
+
+=cut
+
 sub admin_user_domain { 'lincolnshire.gov.uk' }
 
+=item * The default map zoom is set to 5.
+
+=cut
+
 sub default_map_zoom { 5 }
 
+=item * The front page text is tweaked to explain existing report numbers
+can be looked up.
+
+=back
+
+=cut
+
 sub enter_postcode_text {
     my ($self) = @_;
     return 'Enter a Lincolnshire postcode, street name and area, or check an existing report number';
@@ -45,6 +104,13 @@ sub disambiguate_location {
     };
 }
 
+=head2 lookup_site_code_config
+
+We store Lincolnshire's street gazetteer in our Tilma, which is used to
+look up the nearest road to the report for including in the data sent to
+Confirm.
+
+=cut
 
 sub lookup_site_code_config { {
     buffer => 200, # metres
@@ -55,11 +121,16 @@ sub lookup_site_code_config { {
     accept_feature => sub { 1 }
 } }
 
+=head2 categories_restriction
+
+Lincolnshire is a two-tier council, but don't want to display all
+district-level categories on their cobrand - just a few, namely 'Litter',
+'Street nameplates', 'Bench', 'Cycle rack', 'Litter bin', and 'Planter'.
+
+=cut
 
 sub categories_restriction {
     my ($self, $rs) = @_;
-    # Lincolnshire is a two-tier council, but don't want to display
-    # all district-level categories on their cobrand - just a couple.
     return $rs->search( { -or => [
         'body.name' => [ "Lincolnshire County Council", 'National Highways' ],
 
@@ -72,6 +143,28 @@ sub categories_restriction {
     ] } );
 }
 
+=head2 pin_colour
+
+Lincolnshire uses the following pin colours:
+
+=over 4
+
+=item * grey: Not a Lincolnshire problem, or closed as 'not responsible'
+
+=item * orange: 'investigating' or 'for triage'
+
+=item * yellow: 'action scheduled' or 'in progress'
+
+=item * green: Fixed
+
+=item * blue: Otherwise closed
+
+=item * red: Anything else (open)
+
+=back
+
+=cut
+
 sub pin_colour {
     my ( $self, $p, $context ) = @_;
     my $ext_status = $p->get_extra_metadata('external_status_code');
@@ -87,6 +180,13 @@ sub pin_colour {
     return 'red';
 }
 
+=head2 open311_config
+
+Our Confirm integration can handle multiple photos and the direct
+uploading of private photos, so we set the flag for this.
+
+=cut
+
 around 'open311_config' => sub {
     my ($orig, $self, $row, $h, $params) = @_;