Update documentation (#62)

* Add linting test and update README.md
* update copyright year, add tool to update.

CMakeLists.txt

@@ -1,4 +1,4 @@
-
+# (C) British Crown Copyright 2024 Met Office
 ############################################################################################
 # nemo-feedback
 

CPPLINT.cfg

@@ -0,0 +1,3 @@
+set noparent
+linelength=100
+filter=+build,-build/include_alpha,-build/c++11,+legal,+readability,+runtime,+whitespace,-runtime/references

README.md

@@ -1,12 +1,78 @@
-nemo-feedback
-=============
-
 ![CI](https://github.com/MetOffice/nemo-feedback/actions/workflows/ci.yml/badge.svg)
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+© British Crown Copyright 2024 Met Office. All rights reserved.
+
+# nemo-feedback
+
+JEDI UFO filter extension for writing NEMO ocean model NetCDF feedback file format data from the UK Met Office.
+
+## Description
+
+_nemo-feedback_ is a small code snippet that is compiled with UFO to add an additional filter for direct output in NEMO feedback file format. It was developed at the Met Office to interface with the JEDI framework and the [_orca-jedi_](https://github.com/MetOffice/nemo-feedback) JEDI "psuedomodel". These tools are built as a bridge between NEMO/NEMOVAR and the JEDI framework - rather than interfacing directly with NEMO or NEMOVAR, the model state is derived from input files, and the quality controlled observations are written to feedback file for ingestion by the NEMOVAR executable. It is anticipated that _nemo-feedback_ will become obsolete, either through adoption of a standard observation file format across Met Office systems (ODB), or through further integration of Met Office Ocean workflows into the JEDI framework.
+
+## Getting Started
+
+### Dependencies
+
+  * [cmake](https://cmake.org/)
+  * [Unidata/netcdf-cxx4](https://github.com/Unidata/netcdf-cxx4)
+  * [ecmwf/ecbuild](https://github.com/ecmwf/ecbuild)
+  * [ecmwf/eckit](https://github.com/ecmwf/eckit)
+  * [JCSDA/oops](https://github.com/JCSDA/oops)
+  * [JCSDA/ufo](https://github.com/JCSDA/ufo)
+
+### Installing
+
+_nemo-feedback_ meant to be built with UFO as part of [mo-bundle](https://github.com/MetOffice/mo-bundle) at the Met Office - see the README in that project for details on how to build.
+
+Otherwise, it is possible to build _nemo-feedback_ within a custom JEDI bundle. For details about JEDI, including installation instructions see the [jedi-docs](http://jedi-docs.jcsda.org/). A small example of this is part of the continuous integration in this repository.
+
+These bundles are built, made and installed via cmake, and tested with ctest. All code should be documented at the source level for processing using doxygen.
+
+### Using the interface
+
+The jedi configuration is documented in the main jedi documentation. Settings for Met Office operational numerical weather prediction workflows are held internally by the Met Office, however there are some example configurations in the ``examples`` directory as well as the ctest tests inputs (``src/tests/testinputs``). The _nemo-feedback_ filter will work both serially or when using MPI.
+
+The parameters for _nemo-feedback_ are documented in code in the parameters class. When the program is compiled, these are exported to a yaml schema json file, that can be used in conjunction with your editor to highlight any issues with your configuration. An example yaml configuration would look something like:
+
+```yaml
+...
+observations:
+  ...
+  - obs space:
+    ...
+    obs filters:
+    ...
+    - filter: NEMO Feedback Writer
+      reference date:  # eckit::DateTime reference date for the julian day observation time in the file
+      filename: # path to output file
+      observation alias file:  # mapping between observation and model names inside UFO
+      variables:  # List of variables to write
+      - name:  # UFO observation variable name
+        nemo name:  # feedback file variable name
+        long name:  # long name in the netcdf file
+        units: # units attribute in the netcdf file
+        extra variable:  # optional, if true don't make the normal set of sub-variables (e.g for mean-dynamic-topography)
+        additional variables: # "additional" variables (these are extra sub-variables of a variable)
+        - name: # UFO observation variable name
+          feedback suffix: # suffix for this additional variable name (i.e <nemo name>_<feedback suffix>)
+          ioda group: # IODA group to extract this variable from
+...
+```
+
+## Help
+
+See the JEDI documentation for help. Additional debugging/trace output is available when:
+```
+OOPS_DEBUG=true
+OOPS_TRACE=true
+```
+
+## Authors
+
+The current lead maintainer is [@twsearle](https://github.com/twsearle) along with a large amount of help from Met Office contributors (see the "Contributors" page on github).
 
-JEDI UFO filter for writing NEMO ocean model NetCDF feedback file format data from the UK Met Office.
+## Working practices
 
-Installation
-------------
+Please see the [JEDI working principles](https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/latest/working-practices/index.html) for current working practises. There are also templates for issues and PRs should you wish to contribute.
 
-The NEMO feedback file filter is built with UFO and orca-jedi using the orca-bundle.

ci/CMakeLists.txt

@@ -1,7 +1,4 @@
-# (C) Copyright 2022 Met Office
-#
-# This software is licensed under the terms of the Apache Licence Version 2.0
-# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+# (C) British Crown Copyright 2024 Met Office
 
 cmake_minimum_required( VERSION 3.18 FATAL_ERROR )
 

src/CMakeLists.txt

@@ -1,3 +1,5 @@
+# (C) British Crown Copyright 2024 Met Office
+
 add_subdirectory(nemo-feedback)
 add_subdirectory(tests)
 

src/nemo-feedback/CMakeLists.txt

@@ -1,5 +1,4 @@
-# (C) British Crown Copyright 2023 Met Office
-#
+# (C) British Crown Copyright 2024 Met Office
 
 list( APPEND nemo_fdbk_src_files
     instantiateObsFilterFactory.h

src/nemo-feedback/NemoFeedback.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "nemo-feedback/NemoFeedback.h"

src/nemo-feedback/NemoFeedback.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #pragma once

src/nemo-feedback/NemoFeedbackDataCreator.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "nemo-feedback/NemoFeedbackDataCreator.h"

src/nemo-feedback/NemoFeedbackDataCreator.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #pragma once

src/nemo-feedback/NemoFeedbackParameterTraitsOutputDtype.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "nemo-feedback/NemoFeedbackParameterTraitsOutputDtype.h"

src/nemo-feedback/NemoFeedbackParameterTraitsOutputDtype.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #pragma once

src/nemo-feedback/NemoFeedbackParameters.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #pragma once

src/nemo-feedback/feedback_io/Data.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 

src/nemo-feedback/feedback_io/Data.h

@@ -1,17 +1,17 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 
 #pragma once
 
 #include <nemo-feedback/feedback_io/DataIndexer.h>
+#include <nemo-feedback/feedback_io/Utils.h>
 
 #include <string>
 #include <vector>
 #include <memory>
 
-#include <nemo-feedback/feedback_io/Utils.h>
 
 namespace nemo_feedback {
 namespace feedback_io {

src/nemo-feedback/feedback_io/DataIndexer.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 

src/nemo-feedback/feedback_io/DataIndexer.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 

src/nemo-feedback/feedback_io/Utils.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "nemo-feedback/feedback_io/Utils.h"

src/nemo-feedback/feedback_io/Utils.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 

src/nemo-feedback/feedback_io/Writer.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "nemo-feedback/feedback_io/Writer.h"

src/nemo-feedback/feedback_io/Writer.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 

src/nemo-feedback/instantiateObsFilterFactory.h

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #pragma once

src/tests/CMakeLists.txt

@@ -1,9 +1,16 @@
+# (C) British Crown Copyright 2024 Met Office
+
 add_subdirectory(testinput)
 add_subdirectory(testoutput)
 add_subdirectory(Data)
 add_subdirectory(nemo-feedback)
 add_subdirectory(mains)
 
+ecbuild_add_test( TARGET test_nemo_feedback_coding_norms
+                  TYPE SCRIPT
+                  COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/../../tools/cpplint.py
+                  ARGS --recursive ${CMAKE_CURRENT_SOURCE_DIR}/../ )
+
 ecbuild_add_test( TARGET test_nemo_feedback_hofx_ice_writer
                   OMP 1
                   ARGS testinput/hofx_sic_writer.yaml

src/tests/Data/CMakeLists.txt

@@ -1,3 +1,4 @@
+# (C) British Crown Copyright 2024 Met Office
 
 list( APPEND nemofeedback_test_data
 hofx_sic_obs.nc

src/tests/mains/CMakeLists.txt

@@ -1,3 +1,5 @@
+# (C) British Crown Copyright 2024 Met Office
+
 ecbuild_add_executable( TARGET  test_NemoInputsFilters.x
                         SOURCES TestObsFilters.cc
                         LIBS    nemo_feedback ufo oops)

src/tests/mains/TestObsFilters.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include "../test/ufo/ObsFilters.h"

src/tests/nemo-feedback/CMakeLists.txt

@@ -1,3 +1,5 @@
+# (C) British Crown Copyright 2024 Met Office
+
 include_directories( ${PROJECT_SOURCE_DIR}/src )
 
 ecbuild_add_test( TARGET  test_nemo_feedback_writer.x

src/tests/nemo-feedback/test_feedback_data.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include <iostream>

src/tests/nemo-feedback/test_feedback_writer.cc

@@ -1,5 +1,5 @@
 /*
- * (C) British Crown Copyright 2023 Met Office
+ * (C) British Crown Copyright 2024 Met Office
  */
 
 #include<netcdf>

src/tests/testinput/CMakeLists.txt

@@ -1,3 +1,4 @@
+# (C) British Crown Copyright 2024 Met Office
 
 list( APPEND fdbk_writer_test_input
   hofx_sic_writer.yaml

src/tests/testoutput/CMakeLists.txt

@@ -1,3 +1,4 @@
+# (C) British Crown Copyright 2024 Met Office
 
 list( APPEND fdbk_writer_test_output
   test_hofx_sic_writer_out_ref.cdl

tools/copyright_year_update.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+Replace the copyright year in the copyright string on all matching files
+"""
+
+
+import sys
+import re
+from datetime import datetime as dt
+import pathlib
+
+
+def replace_copyright_year(path, old_copyright_year, new_copyright_year):
+    with open(path, "r") as fp:
+        content = fp.read()
+
+    if re.search(old_copyright_year, content):
+        print("Copyright line found")
+        corrected_content = re.sub(old_copyright_year, new_copyright_year, content)
+
+        with open(path, "w") as fp:
+            fp.write(corrected_content)
+
+
+def main():
+    old_copyright = re.escape("British Crown Copyright ") + ".... Met Office"
+
+    new_year = dt.now().year
+    new_copyright = "British Crown Copyright {new_year:d} Met Office".format(
+        new_year=new_year
+    )
+    print("Old Copyright regex: ", old_copyright)
+    print("New Copyright will be: ", new_copyright)
+
+    # walk all files starting from current directory
+    root = pathlib.Path()
+
+    files = (
+        [fl for fl in root.glob("**/*.txt") if fl.is_file()]
+        + [fl for fl in root.glob("**/*.md") if fl.is_file()]
+        + [fl for fl in root.glob("**/*.yaml") if fl.is_file()]
+        + [fl for fl in root.glob("**/*.cc") if fl.is_file()]
+        + [fl for fl in root.glob("**/*.h") if fl.is_file()]
+    )
+
+    for file_path in files:
+        print(f"Replacing copyright year in: {file_path}")
+        replace_copyright_year(file_path, old_copyright, new_copyright)
+
+
+if __name__ == "__main__":
+    main()