Skip to content

Commit 6edbe0c

Browse files
cvvergaracvvergara
committed
(withPoints/doc) Documentation adjustments
1 parent facfa73 commit 6edbe0c

13 files changed

+268
-180
lines changed

‎doc/categories/via-category.rst‎

Lines changed: 17 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -16,22 +16,13 @@ Via - Category
1616

1717
.. official-start
1818
19+
* :doc:`pgr_dijkstraVia`
1920
* :doc:`pgr_withPointsVia`
2021
* :doc:`pgr_trspVia`
2122
* :doc:`pgr_trspVia_withPoints`
2223

2324
.. official-end
2425
25-
.. include:: proposed.rst
26-
:start-after: warning-begin
27-
:end-before: end-warning
28-
29-
.. proposed-start
30-
31-
* :doc:`pgr_dijkstraVia`
32-
33-
.. proposed-end
34-
3526
General Information
3627
-------------------------------------------------------------------------------
3728

@@ -52,76 +43,34 @@ Parameters
5243
**Used in:**
5344

5445
* :doc:`pgr_dijkstraVia`
55-
* :doc:`pgr_trspVia`
56-
57-
.. via_parameters_start
58-
59-
.. list-table::
60-
:width: 81
61-
:widths: 14 20 7 40
62-
:header-rows: 1
63-
64-
* - Parameter
65-
- Type
66-
- Default
67-
- Description
68-
* - `Edges SQL`_
69-
- ``TEXT``
70-
-
71-
- SQL query as described.
72-
* - **via vertices**
73-
- ``ARRAY`` [ **ANY-INTEGER** ]
74-
-
75-
- Array of ordered vertices identifiers that are going to be visited.
76-
77-
Where:
7846

79-
:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
80-
81-
.. via_parameters_end
47+
.. include:: pgr_dijkstraVia.rst
48+
:start-after: via_parameters_start
49+
:end-before: via_parameters_end
8250

8351
**Used in:**
8452

8553
* :doc:`pgr_withPointsVia`
86-
* :doc:`pgr_trspVia_withPoints`
87-
88-
.. via_withPoints_parameters_start
89-
90-
.. list-table::
91-
:width: 81
92-
:widths: auto
93-
:header-rows: 1
9454

95-
* - Parameter
96-
- Type
97-
- Description
98-
* - `Edges SQL`_
99-
- ``TEXT``
100-
- SQL query as described.
101-
* - `Points SQL`_
102-
- ``TEXT``
103-
- SQL query as described.
104-
* - **via vertices**
105-
- ``ARRAY`` [ **ANY-INTEGER** ]
106-
- Array of ordered vertices identifiers that are going to be visited.
55+
.. include:: pgr_withPointsVia.rst
56+
:start-after: via_withPoints_parameters_start
57+
:end-before: via_withPoints_parameters_end
10758

108-
* When positive it is considered a vertex identifier
109-
* When negative it is considered a point identifier
110-
* - **driving side**
111-
- ``CHAR``
112-
- Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
59+
**Used in:**
11360

114-
- [``r``, ``R``] for right driving side (for directed graph only)
115-
- [``l``, ``L``] for left driving side (for directed graph only)
116-
- [``b``, ``B``] for both (only for undirected graph)
61+
* :doc:`pgr_trspVia`
11762

63+
.. include:: TRSP-family.rst
64+
:start-after: via_parameters_start
65+
:end-before: via_parameters_end
11866

119-
Where:
67+
**Used in:**
12068

121-
:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
122-
:ANY-NUMERICAL: SMALLINT, INTEGER, BIGINT, REAL, FLOAT
69+
* :doc:`pgr_trspVia_withPoints`
12370

124-
.. via_withPoints_parameters_end
71+
.. include:: /pgr_trspVia_withPoints.rst
72+
:start-after: trspvia_withPoints_parameters_start
73+
:end-before: trspvia_withPoints_parameters_end
12574

12675
Besides the compulsory parameters each function has, there are optional
12776
parameters that exist due to the kind of function.

‎doc/categories/withPoints-category.rst‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -122,15 +122,34 @@ Parameters
122122
- ``ARRAY[BIGINT]``
123123
- Array of identifiers of ending vertices. Negative values are for point’s
124124
identifiers.
125-
* - **driving side**
125+
126+
.. withPoints_parameters_end
127+
128+
.. driving_side_start
129+
130+
.. list-table::
131+
:width: 81
132+
:widths: 14 14 44
133+
134+
* - [**driving side**]
126135
- ``CHAR``
127136
- Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
128137

129-
- [``r``, ``R``] for right driving side (for directed graph only)
130-
- [``l``, ``L``] for left driving side (for directed graph only)
131-
- [``b``, ``B``] for both (only for undirected graph)
138+
- For directed graph:
132139

133-
.. withPoints_parameters_end
140+
- [``r``, ``R``] for right driving side
141+
- [``l``, ``L``] for left driving side
142+
143+
- For undirected graph:
144+
145+
- [``b``, ``B``] for both driving sides
146+
147+
- Default values when parameter is missing:
148+
149+
- [``r``, ``R``] for directed graph
150+
- [``l``, ``L``] for undirected graph
151+
152+
.. driving_side_end
134153
135154
Optional parameters
136155
...............................................................................

‎doc/dijkstra/pgr_dijkstraVia.rst‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@
88
****************************************************************************
99

1010
.. index::
11-
single: Dijkstra Family ; pgr_dijkstraVia - Proposed
12-
single: Via Category ; pgr_dijkstraVia - Proposed
11+
single: Dijkstra Family ; pgr_dijkstraVia
12+
single: Via Category ; pgr_dijkstraVia
1313
single: dijkstraVia - Proposed
1414

1515
|
1616
17-
``pgr_dijkstraVia`` - Proposed
17+
``pgr_dijkstraVia``
1818
===============================================================================
1919

2020
``pgr_dijkstraVia`` — Route that goes through a list of vertices.
@@ -45,7 +45,7 @@ Signatures
4545
-------------------------------------------------------------------------------
4646

4747
.. index::
48-
single: dijkstraVia - Proposed ; One Via - Proposed on 2.2
48+
single: dijkstraVia ; One Via
4949

5050
One Via
5151
...............................................................................
@@ -69,9 +69,31 @@ One Via
6969
Parameters
7070
-------------------------------------------------------------------------------
7171

72-
.. include:: via-category.rst
73-
:start-after: via_parameters_start
74-
:end-before: via_parameters_end
72+
.. via_parameters_start
73+
74+
.. list-table::
75+
:width: 81
76+
:widths: 14 20 7 40
77+
:header-rows: 1
78+
79+
* - Parameter
80+
- Type
81+
- Default
82+
- Description
83+
* - `Edges SQL`_
84+
- ``TEXT``
85+
-
86+
- SQL query as described.
87+
* - **via vertices**
88+
- ``ARRAY`` [ **ANY-INTEGER** ]
89+
-
90+
- Array of ordered vertices identifiers that are going to be visited.
91+
92+
Where:
93+
94+
:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
95+
96+
.. via_parameters_end
7597
7698
Optional parameters
7799
...............................................................................

‎doc/src/migration.rst‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -872,15 +872,18 @@ After updating pgRouting:
872872
* Use an unnamed valid value for **driving side** after the **distance**
873873
parameter.
874874

875-
.. note:: Validity of **driving side** parameter
875+
.. note:: Default value of **driving side** parameter
876876

877-
**driving side** parameter is unnamed compulsory, and valid values differ for
877+
**driving side** parameter is unnamed, and valid values differ for
878878
directed and undirected graphs.
879879

880-
* Does not have a default value.
881880
* In directed graph: valid values are [``r``, ``R``, ``l``, ``L``]
881+
882+
* Default value = 'r';
883+
882884
* In undirected graph: valid values are [``b``, ``B``]
883-
* Using an invalid value throws an ``ERROR``.
885+
886+
* Default value = 'b';
884887

885888
Single vertex example using ``pgr_withPointsDD``
886889
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1443,7 +1446,7 @@ Starting from `v3.6.0 <https://docs.pgrouting.org/3.6/en/migration.html>`__
14431446
:from: |ksp-result|
14441447
:to: |generic-result|
14451448

1446-
And ``driving side`` parameter changed from named optional to unnamed compulsory
1449+
And ``driving side`` parameter changed from named optional to unnamed
14471450
**driving side** and its validity differ for directed and undirected graphs.
14481451

14491452
Signatures to be migrated:
@@ -1461,13 +1464,19 @@ Signatures to be migrated:
14611464

14621465
* Be aware of the existence of the additional result Columns.
14631466
* New output columns are |generic-result|
1464-
* **driving side** parameter is unnamed compulsory, and valid values differ for
1467+
1468+
.. note:: Default value of **driving side** parameter
1469+
1470+
**driving side** parameter is unnamed, and valid values differ for
14651471
directed and undirected graphs.
14661472

1467-
* Does not have a default value.
14681473
* In directed graph: valid values are [``r``, ``R``, ``l``, ``L``]
1474+
1475+
* Default value = 'r';
1476+
14691477
* In undirected graph: valid values are [``b``, ``B``]
1470-
* Using an invalid value throws an ``ERROR``.
1478+
1479+
* Default value = 'b';
14711480

14721481
``pgr_withPointsKSP`` (`One to One`)
14731482
...............................................................................

‎doc/src/proposed.rst‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,6 @@ Proposed Functions
3030
3131
.. rubric:: Families
3232

33-
:doc:`dijkstra-family`
34-
35-
.. include:: dijkstra-family.rst
36-
:start-after: proposed-start
37-
:end-before: proposed-end
38-
3933
:doc:`transformation-family`
4034

4135
.. include:: transformation-family.rst
@@ -68,12 +62,6 @@ Proposed Functions
6862
:start-after: proposed-start
6963
:end-before: proposed-end
7064

71-
:doc:`via-category`
72-
73-
.. include:: via-category.rst
74-
:start-after: proposed-start
75-
:end-before: proposed-end
76-
7765
See Also
7866
-------------------------------------------------------------------------------
7967

‎doc/trsp/pgr_trspVia_withPoints.rst‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ points with restrictions.
2727
.. rubric:: Version 4.0.0
2828

2929
* Function promoted to official.
30-
* **Driving side** parameter is positional unnamed and compulsory.
30+
* **Driving side** parameter is positional unnamed.
3131

3232
* Valid values depend on kind of graph
3333

@@ -85,7 +85,7 @@ One Via
8585
.. admonition:: \ \
8686
:class: signatures
8787

88-
| pgr_trspVia_withPoints(`Edges SQL`_, `Restrictions SQL`_, `Points SQL`_, **via vertices**, **driving side** [**options**])
88+
| pgr_trspVia_withPoints(`Edges SQL`_, `Restrictions SQL`_, `Points SQL`_, **via vertices**, [**driving side**,] [**options**])
8989
| **options:** ``[directed, strict, U_turn_on_edge, details]``
9090
9191
| Returns set of |via-result|
@@ -101,9 +101,41 @@ One Via
101101
Parameters
102102
-------------------------------------------------------------------------------
103103

104-
.. include:: via-category.rst
105-
:start-after: via_withPoints_parameters_start
106-
:end-before: via_withPoints_parameters_end
104+
.. trspvia_withPoints_parameters_start
105+
106+
.. list-table::
107+
:width: 81
108+
:widths: auto
109+
:header-rows: 1
110+
111+
* - Parameter
112+
- Type
113+
- Description
114+
* - `Edges SQL`_
115+
- ``TEXT``
116+
- SQL query as described.
117+
* - `Restrictions SQL`_
118+
- ``TEXT``
119+
- SQL query as described.
120+
* - `Points SQL`_
121+
- ``TEXT``
122+
- SQL query as described.
123+
* - **via vertices**
124+
- ``ARRAY`` [ **ANY-INTEGER** ]
125+
- Array of ordered vertices identifiers that are going to be visited.
126+
127+
* When positive it is considered a vertex identifier
128+
* When negative it is considered a point identifier
129+
130+
.. include:: withPoints-category.rst
131+
:start-after: driving_side_start
132+
:end-before: driving_side_end
133+
134+
Where:
135+
136+
:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
137+
138+
.. trspvia_withPoints_parameters_end
107139
108140
Optional parameters
109141
...............................................................................

0 commit comments

Comments
 (0)