Merge pull request #27 from sadielbartholomew/add-docs

Add full documentation source & generate built HTML

README.md

@@ -8,8 +8,9 @@
 research which supports the exploration, analysis and plotting of netCDF
 and Met Office format (PP or fields) data.**
 
-It is intended to be an updated
-replacement and improvement on
+![cf-view screenshot preview](docs/source/images/cfview.png "Preview of the cf-view GUI")
+
+It is intended to be an updated replacement and improvement on
 the [xconv+](https://ncas-cms.github.io/xconv-doc/html/index.html) tool,
 using the power of:
 
@@ -29,7 +30,24 @@ research. cf-view is developed and maintained by the
 [NCAS](https://ncas.ac.uk/).
 
 
-![cf-view screenshot preview](media/cfview-screenshot-preview-1.png "Preview of the cf-view GUI")
+#### Features
+
+With cf-view you can, in a self-contained specialised GUI environment:
+
+* Inspect, analyse and manipulate field constructs and their data;
+* Edit, delete and create field metadata and properties;
+* Output the underlying cf-python and cf-plot code;
+* View and produce plots such as map, contour, zonal means, vector, line and
+  trajectory plots;
+* Change plotting properties such as map, colour scale, contour levels and
+  vector properties; and
+* Change interface colour scheme, fonts and font sizes.
+
+Future releases will add support for data:
+
+* with 2D dimensions;
+* defined on rotated pole grids;
+* defined on unstructured grids i.e. UGRID data.
 
 
 ### Documentation

docs/build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 5e5be6f346bcf83ed6701fbc6b84b4cc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/_sources/cfview.rst.txt

@@ -0,0 +1,4 @@
+cfview
+******
+
+.. autofunction:: cfview

docs/build/_sources/download.rst.txt

@@ -0,0 +1,74 @@
+Download/Install
+****************
+
+
+cf-view is available for our supported platforms of Linux and Mac OSX.  If you are using Windows then installing the Microsoft Windows Subsystem for Linux will provide Linux access on that platform.
+
+
+cf-view is already installed on the following computers
+=======================================================
+
+JASMIN: source /home/users/ajh/cfview_install/bin/cfview_setup.sh
+
+ARCHER2: source /home/n02/n02/ajh/cfview_install/bin/cfview_setup.sh
+
+Reading RACC: source /share/apps/NCAS/cfview_install/bin/cfview_setup.sh
+
+
+
+
+To install cf-view
+==================
+
+Simplified install process, download is 400MB, unpacked Python distribution is 1.5GB:
+
+::
+
+   Linux:   wget http://gws-access.jasmin.ac.uk/public/ncas_climate/ajh/cfview_install/cfview_install.sh
+   Mac:     curl -O -L http://gws-access.jasmin.ac.uk/public/ncas_climate/ajh/cfview_install/cfview_install.sh
+   
+   bash cfview_install.sh
+
+
+
+
+Or - make your own installation:
+
+Download and install the latest Miniconda Python if this is not already installed. 
+
+::
+
+   conda update -n base -c defaults conda
+   conda install -c conda-forge pip udunits2 cartopy
+   pip install cf-python cf-plot cf-view
+
+
+A conda-forge package for cf-view is in preparation which will simplify the install process.
+
+
+
+
+
+
+To run cf-view
+==============
+
+::
+
+   cfview <optional netCDF, Met Office PP or fields file(s)>
+
+
+When starting cfview for the first time it might take twenty or so seconds to start while the Matplotlib plotting library does some initialisation.
+
+
+
+|
+|
+|
+|
+|
+|
+|
+| 
+
+

docs/build/_sources/index.rst.txt

@@ -0,0 +1,164 @@
+*********************
+cf-view documentation
+*********************
+
+**Exploration & plotting GUI for netCDF & Met Office format data**
+
+########
+Overview
+########
+
+cf-view is a Graphical User Interface (GUI) for earth science and
+aligned research which supports the exploration, analysis and plotting
+of netCDF and Met Office format (PP or fields) data.
+
+.. image::  images/cfview.png
+   :scale: 40%
+   :alt: Preview of the cf-view GUI
+
+
+It is intended to be an updated replacement and improvement on the
+`xconv+ <https://ncas-cms.github.io/xconv-doc/html/index.html>`__ tool,
+using the power of:
+
+-  Python (`PyQt <https://www.riverbankcomputing.com/software/pyqt/>`__)
+   for the GUI;
+-  `cf-plot <https://github.com/NCAS-CMS/cf-plot>`__ (building on top of
+   `matplotlib <https://matplotlib.org/>`__ and
+   `Cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__) for the
+   plotting;
+-  `cf-python <https://ncas-cms.github.io/cf-python/>`__ for the data
+   reading, processing and analysis; and
+-  `cfdm <https://ncas-cms.github.io/cfdm/>`__ for the underlying data
+   model.
+
+It is designed to be a useful tool for environmental, earth and aligned
+sciences, for example to facilitate climate and meteorological research.
+cf-view is developed and maintained by the
+`NCAS-CMS <https://cms.ncas.ac.uk/index.html>`__ group, part of
+`NCAS <https://ncas.ac.uk/>`__.
+
+
+Features
+^^^^^^^^
+
+With cf-view you can, in a self-contained specialised GUI environment:
+
+- Inspect, analyse and manipulate field constructs and their data;
+- Edit, delete and create field metadata and properties;
+- Output the underlying cf-python and cf-plot code;
+- View and produce plots such as map, contour, zonal means, vector, line and
+  trajectory plots;
+- Change plotting properties such as map, colour scale, contour levels and
+  vector properties; and
+- Change interface colour scheme, fonts and font sizes.
+
+Future releases will add support for data:
+
+- with 2D dimensions;
+- defined on rotated pole grids;
+- defined on unstructured grids i.e. UGRID data.
+
+
+##########
+Quickstart
+##########
+
+After installing (see below), start cf-view through the command line via
+running:
+
+.. code-block:: bash
+
+   cfview
+
+or if you wish to start working with a specific file, add a positional
+argument:
+
+.. code-block:: bash
+
+   cfview <file>
+
+where ``<file>`` is the path to the netCDF, Met Office PP or fields
+file.
+
+*Note:* when starting cf-view for the first time, it might take twenty
+or so seconds to start while matplotlib does some initialisation work.
+
+
+############
+Installation
+############
+
+There are two main ways to install cf-view: through a package manager,
+or by downloading and running a dedicated installation script.
+
+Installation by package manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use ``pip`` with ``conda`` (or similar package managers such as
+``mamba``) as follows.
+
+To use ``pip``, run:
+
+.. code:: bash
+
+   pip install cf-python cf-plot cf-view
+
+In future you will be able to install cf-view and all of its
+dependencies fully with ``conda``, but for now only the dependencies are
+installable this way, like so:
+
+.. code:: bash
+
+   conda install -c ncas -c conda-forge cf-python cf-plot udunits2
+
+and you must use e.g. ``pip`` to install the cf-view library itself.
+
+Installation by download script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Alternatively, to install cf-view with its required dependencies, you
+can download from source. For Linux, run:
+
+.. code:: bash
+
+   wget http://gws-access.jasmin.ac.uk/public/ncas_climate/ajh/cfview_install/cfview_install.sh
+
+or for Mac, instead run:
+
+.. code:: bash
+
+   curl -O -L http://gws-access.jasmin.ac.uk/public/ncas_climate/ajh/cfview_install/cfview_install.sh
+
+and then install by running the ``cfview_install.sh`` script, for
+example with:
+
+.. code:: bash
+
+   bash cfview_install.sh
+
+Further installation information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+More detail about installation is provided on the `installation
+page <https://ajheaps.github.io/cf-view/download.html>`__
+(``https://ajheaps.github.io/cf-view/download.html``) of the
+documentation.
+
+
+############
+Contributing
+############
+
+Everyone is welcome to contribute to cf-view in the form of bug reports,
+documentation, code, design proposals, and more.
+
+Contributing guidelines will be added to the repository shortly.
+
+###############################################
+Help: Issues, Questions, Feature Requests, etc.
+###############################################
+
+For any queries, see the `guidance
+page <https://ajheaps.github.io/cf-view/issues.html>`__
+(``https://ajheaps.github.io/cf-view/issues.html``).

docs/build/_sources/issues.rst.txt

@@ -0,0 +1,27 @@
+cf-view issues
+**************
+
+If you find a problem with cf-view please email [email protected] with the following:
+
+|   (i) A short description of how the error occurs
+|   (ii) The data needed to make the plot.  
+|        Please make the data as small as possible for this. 
+|        i.e. if you have a problem plotting a field then send just this
+|        one field and not the whole set of fields.
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+
+
+

docs/build/_sources/license.rst.txt

@@ -0,0 +1,18 @@
+License
+*******
+
+**Copyright (c) Sadie Bartholomew (NCAS-CMS) 2024**
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
+
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 

docs/build/_sources/roadmap.rst.txt

@@ -0,0 +1,57 @@
+cf-view roadmap
+***************
+
+The current version is |release|
+
+- 2.0 Initial release using Python 3 the PyQt5 widget system
+- 2.1 Improve functionality in the main interface
+- 2.2 Line plots
+- 2.3 Vector plots
+- 2.4 Combined contour and vector plots
+- 2.5 Trajectory plots
+- 2.6 Extend to data that is lacking CF information
+- 2.7 Data and property panels update
+- 2.8 Testing against a variety of input data
+- 2.9 Interim release of internal rewrite
+- 3.0 Rewrite internal code to support more than 4 dimensional data
+- 3.1 Rotated pole data
+- 3.2 Two dimensional X and Y data such as ORCA
+- 3.3 Move from PyQt5 to PyQt6
+- 3.4 UGRID data
+
+
+|
+|
+|
+|
+|
+|
+|
+|
+
+
+
+Requests
+********
+
+Further functionality may be added on request - please email <[email protected]> with the details.
+
+
+
+
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+| 
+|