Added initial metadata item documentation. Refs: #280

arki/Makefile.am

@@ -33,6 +33,7 @@ nobase_dist_arkiinclude_HEADERS = \
 		stream/concrete-parts.tcc \
 		stream/discard.h \
 		stream/buffer.h \
+		stream/text.h \
 		stream/tests.h \
 		defs.h \
 		exceptions.h \

arki/stream.h

@@ -29,6 +29,13 @@ std::ostream& operator<<(std::ostream& out, const SendResult& r);
 }
 
 
+/**
+ * Abstract interface for streaming data.
+ *
+ * This is used for anything in Arkimet that needs to output byte or text
+ * streams, and is generic enough to support both high performance, low-level
+ * implementations, and wrapping other interfaces like Python files.
+ */
 class StreamOutput
 {
 public:

arki/stream/fwd.h

@@ -10,6 +10,7 @@ struct StreamOutput;
 namespace stream {
 
 class TimedOut;
+class Text;
 
 struct SendResult
 {

arki/stream/text.h

@@ -0,0 +1,57 @@
+#ifndef ARKI_STREAM_TEXT_H
+#define ARKI_STREAM_TEXT_H
+
+#include <arki/stream.h>
+#include <string>
+
+namespace arki {
+namespace stream {
+
+struct Text
+{
+    StreamOutput& out;
+    SendResult result;
+
+    Text(StreamOutput& out) : out(out) {}
+
+    void print(const std::string& str)
+    {
+        if (result.flags & SendResult::SEND_PIPE_EOF_DEST)
+            return;
+
+        result += out.send_line(str.data(), str.size());
+    }
+
+    /**
+     * Print a reStructuredText title.
+     *
+     * Level represents the heading level (1 being the outermost one), and
+     * rendering is done according to
+     * https://devguide.python.org/documenting/#sections
+     */
+    void rst_header(const std::string& str, unsigned level=1)
+    {
+        bool over = false;
+        char c = '"';
+
+        switch (level)
+        {
+            case 1: over = true, c = '#'; break;
+            case 2: over = true, c = '*'; break;
+            case 3: c = '='; break;
+            case 4: c = '-'; break;
+            case 5: c = '^'; break;
+        }
+
+        std::string bar(str.size(), c);
+        if (over) print(bar);
+        print(str);
+        print(bar);
+
+    }
+};
+
+}
+}
+
+#endif

arki/types.cc

@@ -7,6 +7,7 @@
 #include "structured/keys.h"
 #include "structured/reader.h"
 #include "formatter.h"
+#include "stream/text.h"
 
 using namespace std;
 using namespace arki::utils;
@@ -179,5 +180,12 @@ std::string tag(types::Code code)
     return types::MetadataType::get(code)->tag;
 }
 
+void Type::document(stream::Text& out)
+{
+    out.rst_header("Metadata types");
+
+    MetadataType::document_types(out, 2);
+}
+
 }
 }

arki/types.h

@@ -6,6 +6,7 @@
 #include <arki/core/fwd.h>
 #include <arki/types/fwd.h>
 #include <arki/structured/fwd.h>
+#include <arki/stream/fwd.h>
 #include <memory>
 #include <vector>
 #include <string>
@@ -181,6 +182,12 @@ class Type
     static std::unique_ptr<Type> decode(core::BinaryDecoder& dec);
     static std::unique_ptr<Type> decodeInner(types::Code, core::BinaryDecoder& dec);
     static std::unique_ptr<Type> decode_inner(types::Code, core::BinaryDecoder& dec, bool reuse_buffer);
+
+    /**
+     * Write reStructuredText documentation about all known metadata types to
+     * the given output stream
+     */
+    static void document(stream::Text& out);
 };
 
 /// Write as a string to an output stream

arki/types/area.cc

@@ -8,6 +8,7 @@
 #include "arki/structured/reader.h"
 #include "arki/structured/keys.h"
 #include "arki/bbox.h"
+#include "arki/stream/text.h"
 #include "arki/libconfig.h"
 #include <sstream>
 
@@ -216,6 +217,20 @@ std::unique_ptr<Area> Area::decode_structure(const structured::Keys& keys, const
     }
 }
 
+void Area::write_documentation(stream::Text& out, unsigned heading_level)
+{
+    out.rst_header("Area", heading_level);
+    out.print(Area::doc);
+
+    out.rst_header(area::GRIB::name, heading_level + 1);
+    out.print(area::GRIB::doc);
+
+    out.rst_header(area::ODIMH5::name, heading_level + 1);
+    out.print(area::ODIMH5::doc);
+
+    out.rst_header(area::VM2::name, heading_level + 1);
+    out.print(area::VM2::doc);
+}
 
 namespace area {
 

arki/types/area.h

@@ -28,16 +28,18 @@ struct traits<Area>
     typedef area::Style Style;
 };
 
-/**
- * The vertical area or layer of some data
- *
- * It can contain information like areatype and area value.
- */
 class Area : public types::Encoded
 {
 protected:
     mutable arki::utils::geos::Geometry* cached_bbox = nullptr;
 
+    constexpr static const char* doc = R"(
+Geographical area relative to a data element.
+
+When possible, Area values should be convertible to coordinate polygons,
+allowing matching using geospatial primitives (contains, intersects, ...).
+)";
+
 public:
     using Encoded::Encoded;
 
@@ -77,6 +79,8 @@ class Area : public types::Encoded
     /// Return the geographical bounding box
     const arki::utils::geos::Geometry* bbox() const;
 
+    static void write_documentation(stream::Text& out, unsigned heading_level);
+
     // Register this type tree with the type system
     static void init();
 };
@@ -89,6 +93,12 @@ inline std::ostream& operator<<(std::ostream& o, Style s) { return o << Area::fo
 class GRIB : public Area
 {
 public:
+    constexpr static const char* name = "GRIB";
+    constexpr static const char* doc = R"(
+Collection of key-value pairs, interpreted in the context of GRIB grid
+definitions.
+)";
+
     using Area::Area;
     ~GRIB();
 
@@ -105,6 +115,12 @@ class GRIB : public Area
 class ODIMH5 : public Area
 {
 public:
+    constexpr static const char* name = "ODIMH5";
+    constexpr static const char* doc = R"(
+Collection of key-value pairs, interpreted in the context of ODIM area
+information.
+)";
+
     using Area::Area;
     ~ODIMH5();
 
@@ -121,6 +137,10 @@ class ODIMH5 : public Area
 class VM2 : public Area
 {
 public:
+    constexpr static const char* name = "VM2";
+    constexpr static const char* doc = R"(
+Area information as an integer VM2 station identifier.
+)";
     using Area::Area;
     ~VM2();
 

arki/types/assigneddataset.h

@@ -54,6 +54,8 @@ struct AssignedDataset : public Encoded
     std::ostream& writeToOstream(std::ostream& o) const override;
     void serialise_local(structured::Emitter& e, const structured::Keys& keys, const Formatter* f=0) const override;
 
+    static void write_documentation(stream::Text& out, unsigned heading_level) {}
+
     // Register this type with the type system
     static void init();
 

arki/types/bbox.h

@@ -74,6 +74,8 @@ class BBox : public types::Encoded
     static std::unique_ptr<BBox> decodeString(const std::string& val);
     static std::unique_ptr<BBox> decode_structure(const structured::Keys& keys, const structured::Reader& val);
 
+    static void write_documentation(stream::Text& out, unsigned heading_level) {}
+
     // Register this type tree with the type system
     static void init();
 

arki/types/level.cc

@@ -6,6 +6,7 @@
 #include "arki/structured/emitter.h"
 #include "arki/structured/reader.h"
 #include "arki/structured/keys.h"
+#include "arki/stream/text.h"
 #include "arki/libconfig.h"
 #include <sstream>
 #include <iomanip>
@@ -867,5 +868,55 @@ void Level::init()
     MetadataType::register_type<Level>();
 }
 
+void Level::write_documentation(stream::Text& out, unsigned heading_level)
+{
+    out.rst_header("Level", heading_level);
+
+    out.rst_header("GRIB1", heading_level + 1);
+    out.print(R"(
+Level represented with as in GRIB version 1:
+* Level type
+* l1 (when applicable, depending on type)
+* l2 (for layer types)
+
+.. note::
+   TODO: add references to manual of codes
+)");
+
+    out.rst_header("GRIB2S", heading_level + 1);
+    out.print(R"(
+Level represented with as in GRIB version 2, surface levels:
+* Level type
+* Scale
+* Value
+
+.. note::
+   TODO: add references to manual of codes
+)");
+
+    out.rst_header("GRIB2D", heading_level + 1);
+    out.print(R"(
+Level represented with as in GRIB version 2, layer levels:
+* Type of first level
+* Scale of first level
+* Value of first level
+* Type of second level
+* Scale of second level
+* Value of second level
+
+.. note::
+   TODO: add references to manual of codes
+)");
+
+    out.rst_header("ODIMH5", heading_level + 1);
+    out.print(R"(
+Level represented with as in ODIM, either as a single floating point value, or
+as two floating point minimum, maximum values.
+
+.. note::
+   TODO: find meanings of ODIM values
+)");
+}
+
 }
 }

arki/types/level.h

@@ -95,6 +95,8 @@ class Level : public types::Encoded
                                              uint8_t type2, uint8_t scale2, uint32_t val2);
     static std::unique_ptr<Level> createODIMH5(double value);
     static std::unique_ptr<Level> createODIMH5(double min, double max);
+
+    static void write_documentation(stream::Text& out, unsigned heading_level);
 };
 
 namespace level {

arki/types/note.cc

@@ -5,6 +5,7 @@
 #include "arki/structured/emitter.h"
 #include "arki/structured/reader.h"
 #include "arki/structured/keys.h"
+#include "arki/stream/text.h"
 #include <sstream>
 
 #define CODE TYPE_NOTE
@@ -120,5 +121,12 @@ void Note::init()
     MetadataType::register_type<Note>();
 }
 
+void Note::write_documentation(stream::Text& out, unsigned heading_level)
+{
+    out.rst_header("Note", heading_level);
+
+    out.print(Note::doc);
+}
+
 }
 }

arki/types/note.h

@@ -20,6 +20,14 @@ struct traits<Note>
  */
 class Note : public Encoded
 {
+    constexpr static const char* doc = R"(
+A timestamped annotation about how arkimet processed this element.
+
+This can be used to track and audit the life of data in the archive.
+
+It can be used for consultation only, and cannot be used in searches.
+)";
+
 public:
     using Encoded::Encoded;
 
@@ -48,6 +56,8 @@ class Note : public Encoded
     /// Create a note with the given time and content
     static std::unique_ptr<Note> create(const core::Time& time, const std::string& content);
     static std::unique_ptr<Note> decode_structure(const structured::Keys& keys, const structured::Reader& val);
+
+    static void write_documentation(stream::Text& out, unsigned heading_level);
 };
 
 }