Trsp enhancement (#2354)

trsp * [code] adding path_id column * [sql] adding path_id column * [docqueries] adjusting results * [pgtap] * adding path_id column to general result * adjusting tests * [doc] fixing & adjusting documentation * [locale] updating the locale
aryan1010 · Jul 12, 2022 · d2a4ab3 · d2a4ab3
1 parent 4dc8987
commit d2a4ab3
Show file tree

Hide file tree

Showing 41 changed files with 2,664 additions and 1,920 deletions.
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
@@ -11,7 +11,41 @@ div.content-wrapper {
 }
 
 div.topic {
-        border: none;
+    border: none;
+}
+
+p.admonition-title {
+    font-weight: bold;
+    background-color: aqua;
+    border: #000000;
+}
+
+.alert-warning {
+    color: #333;
+}
+
+.alert-info {
+    color: #333;
+}
+
+div.note {
+    background-color: white;
+    background-image: none;
+}
+
+div.warning {
+    background-color: white;
+    background-image: none;
+}
+
+div.signatures {
+    font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
+    background-image: none;
+    background-color: #f5f5f5;
+    border: 1px solid #ccc;
+    color: #333;
+    font-size: 13px;
+    word-break: keep-all;
 }
 
 code.literal {

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -86,7 +86,7 @@ release = '@PROJECT_FULL_VERSION@'
 # for a list of supported languages.
 language = 'en'
 locale_dirs = ['@CMAKE_SOURCE_DIR@/locale/']
-#gettext_compact = False
+
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -99,15 +99,9 @@ locale_dirs = ['@CMAKE_SOURCE_DIR@/locale/']
 exclude_patterns = [
     ]
 
-#    'src/pickDeliver/doc/pgr_withPointsVia.rst',
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
 
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
 add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
@@ -120,6 +114,15 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# -- Options for internationalization ---------------------------------------------------
+
+gettext_allow_fuzzy_translations = True
+gettext_location = True
+#gettext_uuid = True
+#gettext_additional_targets = [ ]
+#gettext_compact = "docs"
+
+
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -346,6 +349,8 @@ linkcheck_anchors = False
 rst_epilog="""
 .. |ANY-INTEGER| replace:: :abbr:`ANY-INTEGER(SMALLINT, INTEGER, BIGINT)`
 .. |ANY-NUMERICAL| replace:: :abbr:`ANY-NUMERICAL(SMALLINT, INTEGER, BIGINT, REAL, FLOAT)`
+.. |generic-result| replace:: (seq, path_id, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
+.. |via-result| replace:: (seq, path_id, path_seq, start_vid, end_vid, node, edge, cost, agg_cost, route_agg_cost)
 """
 
 # Create a compressed PDF

diff --git a/doc/trsp/TRSP-family.rst b/doc/trsp/TRSP-family.rst
@@ -64,7 +64,7 @@ Road restrictions are a sequence of road segments that can not be taken in a
 sequential manner.
 Some restrictions are implicit on a directed graph, for example, one way roads
 where the wrong way edge is not even inserted on the graph.
-But normally on turns like **left turn** or **right turn**, hence the name turn
+But normally on turns like no left turn or no right turn, hence the name turn
 restrictions, there are sometimes restrictions.
 
 .. image:: images/restrictions.png
@@ -112,7 +112,7 @@ Restrictions
 On road networks, there are restrictions such as left or right turn restrictions,
 no U turn restrictions.
 
-A restriction is a sequence of edges, called **path** and that **path** is to be
+A restriction is a sequence of edges, called path and that path is to be
 avoided.
 
 .. TODO update the image

diff --git a/doc/trsp/pgr_trsp.rst b/doc/trsp/pgr_trsp.rst
@@ -28,30 +28,39 @@
 pgr_trsp - Proposed
 ===============================================================================
 
-
 ``pgr_trsp`` - routing vertices with restrictions.
 
+.. figure:: images/boost-inside.jpeg
+   :target: https://www.boost.org/libs/graph/doc/table_of_contents.html
+
+   Boost Graph Inside
+
+.. include:: proposed.rst
+   :start-after: begin-warning
+   :end-before: end-warning
+
 .. rubric:: Availability
 
 * Version 3.4.0
 
-  * New **Proposed** signatures
+  * New proposed signatures:
 
     * ``pgr_trsp`` (`One to One`_)
     * ``pgr_trsp`` (`One to Many`_)
     * ``pgr_trsp`` (`Many to One`_)
     * ``pgr_trsp`` (`Many to Many`_)
     * ``pgr_trsp`` (`Combinations`_)
 
-  * Deprecated signatures
-     * ``pgr_trsp(text,integer,integer,boolean,boolean,text)``
-     * ``pgr_trsp(text,integer,float,integer,float,boolean,boolean,text)``
-     * ``pgr_trspViaVertices(text,anyarray,boolean,boolean,text)``
-     * ``pgr_trspviaedges(text,integer[],double precision[],boolean,boolean,text)``
+  * Deprecated signatures:
+
+    * ``pgr_trsp(text,integer,integer,boolean,boolean,text)``
+    * ``pgr_trsp(text,integer,float,integer,float,boolean,boolean,text)``
+    * ``pgr_trspViaVertices(text,anyarray,boolean,boolean,text)``
+    * ``pgr_trspviaedges(text,integer[],double precision[],boolean,boolean,text)``
 
 * Version 2.1.0
 
-  * New *Via* **prototypes**
+  * New prototypes:
 
     * ``pgr_trspViaVertices``
     * ``pgr_trspViaEdges``
@@ -69,56 +78,47 @@ real world navigable road networks.
 
 The main characteristics are:
 
-* Automatic detection of ``reverse_cost`` column
-* Accepts **ANY-INTEGER** and **ANY-NUMERICAL** on input columns
-* All variations give as result the same columns
-* It does no guarantee the shortest path as it might contain restriction paths
+* It does no guarantee the shortest path as it might contain restriction paths.
 
 The general algorithm is as follows:
 
-* Execute a Dijkstra
-* If the solution passes thru a restriction then
+* Execute a Dijkstra.
+* If the solution passes thru a restriction then.
 
-  * Execute the **TRSP** algorithm with restrictions
+  * Execute the **TRSP** algorithm with restrictions.
 
 Signatures
 -------------------------------------------------------------------------------
 
 .. rubric:: Proposed
 
-.. include:: proposed.rst
-   :start-after: begin-warning
-   :end-before: end-warning
+.. admonition:: \ \
+   :class: signatures
 
-.. parsed-literal::
-
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vid,  end vid
-               [, directed]) -- Proposed on v3.4
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vid,  end vids
-               [, directed]) -- Proposed on v3.4
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vids, end vid
-               [, directed]) -- Proposed on v3.4
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vids, end vids
-               [, directed]) -- Proposed on v3.4
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, `Combinations SQL`_,
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   | pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vid**, **end vid**, [directed])
+   | pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vid**, **end vids**, [ directed])
+   | pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vids**, **end vid**, [directed])
+   | pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vids**, **end vids**, [directed])
+   | pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, `Combinations SQL`_, [directed])
+
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
 .. index::
     single: trsp(One to One) -- Proposed on v3.4
 
 One to One
 ...............................................................................
 
-.. parsed-literal::
+.. admonition:: \ \
+   :class: signatures
+
+   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vid**, **end vid**, [directed])
 
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vid,  end vid
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
-:Example: From vertex :math:`6` to vertex  :math:`10` on an **undirected** graph
+:Example: From vertex :math:`6` to vertex  :math:`10` on an undirected graph.
 
 .. literalinclude:: doc-trsp.queries
    :start-after: -- q2
@@ -130,15 +130,16 @@ One to One
 One to Many
 ...............................................................................
 
-.. parsed-literal::
+.. admonition:: \ \
+   :class: signatures
 
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vid,  end vids
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vid**, **end vids**, [directed])
+
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
 :Example: From vertex :math:`6` to vertices :math:`\{10, 1\}` on an
-          **undirected** graph
+          undirected graph.
 
 .. literalinclude:: doc-trsp.queries
    :start-after: -- q3
@@ -150,15 +151,17 @@ One to Many
 Many to One
 ...............................................................................
 
-.. parsed-literal::
+.. admonition:: \ \
+   :class: signatures
+
+   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vids**, **end vid**,
+   [directed])
 
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vids, end vid
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
-:Example: From vertices :math:`\{6, 1\}` to vertex :math:`8` on a **directed**
-          graph
+:Example: From vertices :math:`\{6, 1\}` to vertex :math:`8` on a directed
+          graph.
 
 .. literalinclude:: doc-trsp.queries
    :start-after: -- q4
@@ -170,15 +173,17 @@ Many to One
 Many to Many
 ...............................................................................
 
-.. parsed-literal::
+.. admonition:: \ \
+   :class: signatures
 
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, start vids, end vids
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, **start vids**, **end vids**,
+   [directed])
+
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
 :Example: From vertices :math:`\{6, 1\}` to vertices :math:`\{10, 8\}` on an
-          **undirected** graph
+          undirected graph.
 
 .. literalinclude:: doc-trsp.queries
    :start-after: -- q5
@@ -190,14 +195,15 @@ Many to Many
 Combinations
 ...............................................................................
 
-.. parsed-literal::
+.. admonition:: \ \
+   :class: signatures
+
+   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, `Combinations SQL`_, [directed])
 
-   pgr_trsp(`Edges SQL`_, `Restrictions SQL`_, `Combinations SQL`_,
-               [, directed]) -- Proposed on v3.4
-   RETURNS (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
-   OR EMPTY SET
+   | RETURNS SET OF |generic-result|
+   | OR EMPTY SET
 
-:Example: Using a combinations table on an **undirected** graph
+:Example: Using a combinations table on an undirected graph.
 
 .. literalinclude:: doc-trsp.queries
    :start-after: -- q6