ECC-200: doxygen for python

doxygen/eccodes.dox

@@ -12,77 +12,24 @@ set of tools for decoding and encoding messages in the following formats:
 A useful set of <a href="https://software.ecmwf.int/wiki/display/ECC/Command+line+tools">command line tools</a>
 provide quick access to the messages. C, Fortran 90 and Python interfaces provide access to the main ecCodes functionality.
 
-ecCodes is an evolution of <a href="https://software.ecmwf.int/wiki/display/GRIB/Home">GRIB-API</a>.  It is designed to provide the user with a simple set of functions to access
+ecCodes is an evolution of <a href="https://software.ecmwf.int/wiki/display/GRIB/Home">GRIB-API</a>.  It is designed to provide the user with a simple set of functions to access data from several formats with a key/value approach.
-data from several formats with a key/value approach.
 
 For GRIB encoding and decoding, the GRIB-API functionality is provided fully in ecCodes with the same user interface and behaviour. Interfaces for C, Fortran 90 and Python are all maintained as in GRIB-API.  However, the GRIB-API Fortran 77 interface is no longer available.
 
 In addition, a new set of functions with the prefix "codes_" is provided to operate on all the supported message formats. These functions have the same interface and behaviour as the "grib_" functions. 
 
-A selection of GRIB-API tools  has been included in ecCodes (ecCodes GRIB tools), while new tools are available for the BUFR (ecCodes BUFR tools) and GTS formats. The new tools have been developed to be as similar as possible to the existing GRIB-API tools maintaining, where possible, the same options and behaviour. A significant difference compared with GRIB-API tools is that bufr_dump produces output in json format which can be used in many web based applications.
+A selection of GRIB-API tools has been included in ecCodes (<a href="https://software.ecmwf.int/wiki/display/ECC/GRIB+tools">ecCodes GRIB tools</a>),
+while new tools are available for the BUFR (<a href="https://software.ecmwf.int/wiki/display/ECC/BUFR+tools">ecCodes BUFR tools</a>) and GTS formats.
+The new tools have been developed to be as similar as possible to the existing GRIB-API tools maintaining, where possible, the same options and behaviour. A significant difference compared with GRIB-API tools is that bufr_dump produces output in <a href="https://en.wikipedia.org/wiki/JSON">JSON</a> format which can be used in many web based applications.
 
 Migration from GRIB-API to ecCodes is expected to be transparent for current GRIB-API users. The GRIB-API library is fully available in the ecCodes library.  Users are encouraged to test their GRIB-API applications by linking with the ecCodes library and to provide feedback of any problems encountered.
 
+\warning Name clashes prevent a simultaneous use of the GRIB-API and ecCodes libraries. For this reason, and to simplify the software maintenance, it is planned to replace the GRIB-API library by ecCodes in a timeframe of the order of one year.  The "grib_" functions will, however, be maintained in the ecCodes library.
 
-
+#########
-##############
-The ecCodes library is written entirely in C and some command line \ref tools "tools" are 
-provided to give a quick way to manipulate GRIB and BUFR data. Moreover a \ref eccodes "Fortran interface 90" is available
-giving access to the main features of the C library.
-
-The library is designed to access and modify messages in both editions with the same
-\ref get_set "function calls" using a set of \ref keys to access the coded information 
-( examples: \ref grib_get_keys.f90 "grib_get_keys.f90" \ref set.f90 "set.f90", \ref grib_get_keys.c "grib_get_keys.c", \ref set.c "set.c", \ref grib_get_examples "grib_get", \ref grib_set_examples "grib_set" ). 
-
-The \ref keys "keys" available for a message are different depending not only on the edition
-but also and mainly on the type of each message and the information it contains. 
-A list of all the available keys in a message can be obtained dynamically using the 
-library as shown in \ref keys_iterator.c "keys_iterator.c" or using the \ref tools 
-as shown in \ref grib_dump_examples "grib_dump" or \ref grib_keys_examples "grib_keys".
-
-GRIB API will replace the GRIBEX function and a 
-<a href="/publications/manuals/grib_api/gribexkeys/callGribex.html">table of conversion</a> between the
-numeric encoding of GRIBEX and the alphanumeric keys of GRIB API is provided to help
-the migration.
-
-To learn how to use the grib_api we recommend the user works through the \ref grib_examples.
-
 Reference manuals are also provided for the C library (organized in \ref modules), for the 
 \ref eccodes "Fortran 90 interface" and for the \ref gribapi "Python interface".
 
-
+<a href="https://software.ecmwf.int/wiki/display/ECC/ecCodes+installation">Installation instructions</a> are also provided.
-\ref installation "Installation" instructions are also provided.
-
-\section ecwf_users Compiling and linking on ECMWF platforms
-
-ecCodes is installed on all systems at ECMWF with both its components: the library
-and the tools.\n
-The latest version of the tools is always available in the system PATH so that
-users can begin using the tools immediately by typing directly the tool name (\ref tools "see tools reference").\n
-The latest version of the library is also installed on any platform and it is available for linking through the
-following two environment variables: $ECCODES_INCLUDE $ECCODES_LIB.\n\n
-Here is a short summary on how to compile and link on ECMWF systems:\n
-
-- ecgate, hpce, hpcf
-\verbatim
-> xlc -o foo foo.c $ECCODES_INCLUDE $ECCODES_LIB -lm
-\endverbatim \n
-\verbatim
-> xlf90 -o foo foo.f90 $ECCODES_INCLUDE $ECCODES_LIB
-\endverbatim\n
-- linux cluster (C programs)
-\verbatim
-> gcc -m32 -o foo foo.c $ECCODES_INCLUDE $ECCODES_LIB 
-\endverbatim \n
-- workstation (C programs)
-\verbatim
-> gcc -o foo foo.c $ECCODES_INCLUDE $ECCODES_LIB 
-\endverbatim \n
-- linux cluster,workstation (Fortran programs)
-\verbatim
-> use pgf90
-> pgf90 -o foo foo.f90 $ECCODES_INCLUDE $ECCODES_LIB
-\endverbatim\n
-
 
 */

doxygen/grib_api_wiz.cfg

@@ -91,7 +91,7 @@ INPUT                  = eccodes.dox \
                          ../examples/C \
                          ../examples/F90 \
                          ../examples/python \
-                         ../python/gribapi.py \
+                         eccodes.py \
                          environment.dox
 FILE_PATTERNS          = *.c \
                          *.cc \

doxygen/make_dox.sh

@@ -10,6 +10,8 @@ set -e
 
 ./process_C_header.pl ../src/grib_api.h ../src/eccodes.h > eccodes.h
 
+./process_python.pl ../python/gribapi.py > eccodes.py
+
 rm -fr ../html/*
 touch ../html/Makefile.am
 doxygen grib_api_wiz.cfg
@@ -19,3 +21,4 @@ doxygen grib_api_wiz.cfg
 
 # Remove temp files
 rm -f eccodes.h
+rm -f eccodes.py

doxygen/process_python.pl

@@ -0,0 +1,110 @@
+#!/usr/bin/env perl
+use Data::Dumper;
+use strict;
+
+$|=1;
+my $debug = 0;
+
+#if (scalar @ARGV < 1) {
+#  &usage;
+#}
+
+while (<>) {
+
+    s/\@package gribapi/\@package eccodes/;
+
+    s/\bGRIB_CHECK\b/CODES_CHECK/;
+
+    s/\bGRIB_MISSING_DOUBLE\b/CODES_MISSING_DOUBLE/;
+    s/\bGRIB_MISSING_LONG\b/CODES_MISSING_LONG/;
+
+    s/\bgrib_new_from_file\b/codes_grib_new_from_file/;
+    s/\bbufr_new_from_file\b/codes_bufr_new_from_file/;
+    s/\bmetar_new_from_file\b/codes_metar_new_from_file/;
+    s/\bgts_new_from_file\b/codes_gts_new_from_file/;
+    s/\bany_new_from_file\b/codes_any_new_from_file/;
+
+    s/\bgrib_count_in_file\b/codes_count_in_file/;
+    s/\bgrib_multi_support_on\b/codes_grib_multi_support_on/;
+    s/\bgrib_multi_support_off\b/codes_grib_multi_support_off/;
+    s/\bgrib_release\b/codes_release/;
+    s/\bgrib_get_string\b/codes_get_string/;
+    s/\bgrib_set_string\b/codes_set_string/;
+    s/\bgrib_gribex_mode_on\b/codes_gribex_mode_on/;
+    s/\bgrib_gribex_mode_off\b/codes_gribex_mode_off/;
+    s/\bgrib_write\b/codes_write/;
+    s/\bgrib_multi_write\b/codes_grib_multi_write/;
+    s/\bgrib_multi_append\b/codes_grib_multi_append/;
+    s/\bgrib_get_size\b/codes_get_size/;
+    s/\bgrib_get_string_length\b/codes_get_string_length/;
+    s/\bgrib_skip_computed\b/codes_skip_computed/;
+    s/\bgrib_skip_coded\b/codes_skip_coded/;
+    s/\bgrib_skip_edition_specific\b/codes_skip_edition_specific/;
+    s/\bgrib_skip_duplicates\b/codes_skip_duplicates/;
+    s/\bgrib_skip_read_only\b/codes_skip_read_only/;
+    s/\bgrib_skip_function\b/codes_skip_function/;
+    s/\bgrib_iterator_new\b/codes_grib_iterator_new/;
+    s/\bgrib_iterator_delete\b/codes_grib_iterator_delete/;
+    s/\bgrib_iterator_next\b/codes_grib_iterator_next/;
+    s/\bgrib_keys_iterator_new\b/codes_keys_iterator_new/;
+    s/\bgrib_keys_iterator_next\b/codes_keys_iterator_next/;
+    s/\bgrib_keys_iterator_delete\b/codes_keys_iterator_delete/;
+    s/\bgrib_keys_iterator_get_name\b/codes_keys_iterator_get_name/;
+    s/\bgrib_keys_iterator_rewind\b/codes_keys_iterator_rewind/;
+    s/\bgrib_get_long\b/codes_get_long/;
+    s/\bgrib_get_double\b/codes_get_double/;
+    s/\bgrib_set_long\b/codes_set_long/;
+    s/\bgrib_set_double\b/codes_set_double/;
+    s/\bgrib_new_from_samples\b/codes_new_from_samples/;
+    s/\bgrib_clone\b/codes_clone/;
+    s/\bgrib_set_double_array\b/codes_set_double_array/;
+    s/\bgrib_get_double_array\b/codes_get_double_array/;
+    s/\bgrib_set_long_array\b/codes_set_long_array/;
+    s/\bgrib_get_long_array\b/codes_get_long_array/;
+    s/\bgrib_multi_new\b/codes_grib_multi_new/;
+    s/\bgrib_multi_release\b/codes_grib_multi_release/;
+    s/\bgrib_copy_namespace\b/codes_copy_namespace/;
+    s/\bgrib_index_new_from_file\b/codes_index_new_from_file/;
+    s/\bgrib_index_add_file\b/codes_index_add_file/;
+    s/\bgrib_index_release\b/codes_index_release/;
+    s/\bgrib_index_get_size\b/codes_index_get_size/;
+    s/\bgrib_index_get_long\b/codes_index_get_long/;
+    s/\bgrib_index_get_string\b/codes_index_get_string/;
+    s/\bgrib_index_get_double\b/codes_index_get_double/;
+    s/\bgrib_index_select_long\b/codes_index_select_long/;
+    s/\bgrib_index_select_double\b/codes_index_select_double/;
+    s/\bgrib_index_select_string\b/codes_index_select_string/;
+    s/\bgrib_new_from_index\b/codes_new_from_index/;
+    s/\bgrib_get_message_size\b/codes_get_message_size/;
+    s/\bgrib_get_message_offset\b/codes_get_message_offset/;
+    s/\bgrib_get_double_element\b/codes_get_double_element/;
+    s/\bgrib_get_double_elements\b/codes_get_double_elements/;
+    s/\bgrib_get_elements\b/codes_get_elements/;
+    s/\bgrib_set_missing\b/codes_set_missing/;
+    s/\bgrib_set_key_vals\b/codes_set_key_vals/;
+    s/\bgrib_is_missing\b/codes_is_missing/;
+    s/\bgrib_is_defined\b/codes_is_defined/;
+    s/\bgrib_find_nearest\b/codes_grib_find_nearest/;
+    s/\bgrib_get_native_type\b/codes_get_native_type/;
+    s/\bgrib_get\b/codes_get/;
+    s/\bgrib_get_array\b/codes_get_array/;
+    s/\bgrib_get_values\b/codes_get_values/;
+    s/\bgrib_set_values\b/codes_set_values/;
+    s/\bgrib_set\b/codes_set/;
+    s/\bgrib_set_array\b/codes_set_array/;
+    s/\bgrib_index_get\b/codes_index_get/;
+    s/\bgrib_index_select\b/codes_index_select/;
+    s/\bgrib_index_write\b/codes_index_write/;
+    s/\bgrib_index_read\b/codes_index_read/;
+    s/\bgrib_no_fail_on_wrong_length\b/codes_no_fail_on_wrong_length/;
+    s/\bgrib_gts_header\b/codes_gts_header/;
+    s/\bgrib_get_api_version\b/codes_get_api_version/;
+    s/\bgrib_get_message\b/codes_get_message/;
+    s/\bgrib_new_from_message\b/codes_new_from_message/;
+    s/\bgrib_set_definitions_path\b/codes_set_definitions_path/;
+    s/\bgrib_set_samples_path\b/codes_set_samples_path/;
+
+    s/\bGribInternalError\b/CodesInternalError/;
+    
+    print;
+}