Deprecating pgr_createVerticesTable

- Removing use on doc, pgtap and docqueries
- (doc) documenting changes on release notes & NEWS

Author: cvvergara

NEWS.md

@@ -40,6 +40,8 @@ milestone for 3.8.0
   pgr_analyzeOneWay
 * [#2753](https://github.com/pgRouting/pgrouting/issues/2753):
   pgr_analyzeGraph
+* [#2750](https://github.com/pgRouting/pgrouting/issues/2750):
+  pgr_createTopology
 * [#2826](https://github.com/pgRouting/pgrouting/issues/2826):
   pgr_createVerticesTable
 

doc/_static/page_history.js

@@ -220,7 +220,7 @@ var filesArr = [
     ]),
     new createInfo('pgr_createTopology', '2.0', [
         { v: '2.1', n: 'src/common/doc/functions/create_topology'},
-        { v: '2.3', n: 'src/topology/doc/pgr_createTopology'},
+        { v: '2.3', n: 'src/topology/doc/pgr_createTopology'}, 3.8
     ]),
     new createInfo('pgr_analyzeOneWay', '2.0', [
         { v: '2.1', n: 'src/common/doc/functions/analyze_oneway'},

doc/src/migration.rst

@@ -24,6 +24,25 @@ Results can be different because of the changes.
 .. contents:: Contents
    :depth: 2
 
+.. migrate_pgr_createTopology_start
+
+Migration of ``pgr_createTopology``
+-------------------------------------------------------------------------------
+
+Starting from `v3.8.0 <https://docs.pgrouting.org/3.8/en/migration.html>`__
+
+**Before Deprecation:** The following was calculated:
+
+* A table with `<edges>_vertices_pgr` was created.
+
+**After Deprecation:** The user is responsible to create the complete topology.
+
+.. include:: pgRouting-concepts.rst
+   :start-after: createTopology_start
+   :end-before: createTopology_end
+
+.. migrate_pgr_createTopology_end
+
 .. migrate_pgr_createVerticesTable_start
 
 Migration of ``pgr_createVerticesTable``

doc/src/pgRouting-concepts.rst

@@ -489,6 +489,7 @@ The use of indexes on the database design in general:
 Please consult the `PostgreSQL <https://www.postgresql.org/docs/>`__
 documentation and the `PostGIS <https://postgis.net/>`__ documentation.
 
+.. createTopology_start
 
 Build a routing topology
 ...............................................................................
@@ -516,10 +517,18 @@ If the columns do not exist they need to be added to the table in question. (see
 The function :doc:`pgr_extractVertices` is used to create a vertices table
 based on the edge identifier and the geometry of the edge of the graph.
 
+.. literalinclude:: concepts.queries
+   :start-after: -- createTopology1
+   :end-before: -- createTopology2
+
 Finally using the data stored on the vertices tables the ``source`` and
 ``target`` are filled up.
 
-See :doc:`sampledata` for an example for building a topology.
+.. literalinclude:: concepts.queries
+   :start-after: -- createTopology2
+   :end-before: -- createTopology3
+
+.. createTopology_end
 
 Data coming from OSM and using `osm2pgrouting
 <https://github.com/pgRouting/osm2pgrouting>`__ as an import tool, comes with

doc/src/release_notes.rst

@@ -72,6 +72,8 @@ milestone for 3.8.0
   pgr_analyzeOneWay
 * `#2753 <https://github.com/pgRouting/pgrouting/issues/2753>`__:
   pgr_analyzeGraph
+* `#2750 <https://github.com/pgRouting/pgrouting/issues/2750>`__:
+  pgr_createTopology
 * `#2826 <https://github.com/pgRouting/pgrouting/issues/2826>`__:
   pgr_createVerticesTable
 

doc/topology/pgr_analyzeGraph.rst

@@ -55,8 +55,6 @@ The edge table to be analyzed must contain a source column and a target column
 filled with id's of the vertices of the segments and the corresponding vertices
 table <edge_table>_vertices_pgr that stores the vertices information.
 
-- Use :doc:`pgr_createTopology` to create the topology and the vertices table.
-
 Parameters
 -------------------------------------------------------------------------------
 
@@ -95,9 +93,6 @@ The function returns:
 
 .. rubric:: The Vertices Table
 
-The vertices table can be created with
-:doc:`pgr_createTopology <pgr_createTopology>`
-
 The structure of the vertices table is:
 
 :id: ``bigint`` Identifier of the vertex.

doc/topology/pgr_analyzeOneWay.rst

@@ -64,8 +64,6 @@ The edge table to be analyzed must contain a source column and a target column
 filled with id's of the vertices of the segments and the corresponding vertices
 table <edge_table>_vertices_pgr that stores the vertices information.
 
-- Use :doc:`pgr_createTopology` to create the topology and the vertices table.
-
 |Boost| Boost Graph Inside
 
 Signatures
@@ -96,10 +94,6 @@ Parameters
 :two_way_if_null: ``boolean`` flag to treat oneway NULL values as
                   bi-directional. Default value is ``true``.
 
-.. note::
-   It is strongly recommended to use the named notation. See
-   :doc:`pgr_createTopology` for examples.
-
 The function returns:
 
 - ``OK`` after the analysis has finished.
@@ -120,9 +114,6 @@ condition.
 
 .. rubric:: The Vertices Table
 
-The vertices table can be created with
-:doc:`pgr_createTopology`
-
 The structure of the vertices table is:
 
 :id: ``bigint`` Identifier of the vertex.

doc/topology/pgr_createTopology.rst

@@ -8,24 +8,32 @@
    ****************************************************************************
 
 .. index::
-   single: Topology Family ; pgr_createTopology
-   single: createTopology
+   single: Topology Family ; pgr_createTopology - Deprecated since v3.8.0
+   single: createTopology - Deprecated since v3.8.0
 
 |
 
-``pgr_createTopology``
+``pgr_createTopology`` - Deprecated since v3.8.0
 ===============================================================================
 
 ``pgr_createTopology`` — Builds a network topology based on the geometry
 information.
 
 .. rubric:: Availability
 
+* Version 3.8.0
+
+  * Deprecated function.
+
 * Version 2.0.0
 
   * Official function.
   * Renamed from version 1.x
 
+.. include:: migration.rst
+   :start-after: migrate_pgr_createTopology_start
+   :end-before: migrate_pgr_createTopology_end
+
 Description
 -------------------------------------------------------------------------------
 

doc/topology/pgr_createVerticesTable.rst

@@ -286,8 +286,6 @@ See Also
 * :doc:`sampledata`
 * :doc:`topology-functions` for an overview of a topology for routing
   algorithms.
-* :doc:`pgr_createTopology` <pgr_create_topology>` to create a topology based on
-  the geometry.
 
 .. rubric:: Indices and tables
 

doc/topology/pgr_nodeNetwork.rst

@@ -78,10 +78,8 @@ The output table will have for ``edge_table_noded``
 :id: ``bigint`` Unique identifier for the table
 :old_id: ``bigint`` Identifier of the edge in original table
 :sub_id: ``integer`` Segment number of the original edge
-:source: ``integer`` Empty source column to be used with
-         :doc:`pgr_createTopology` function
-:target: ``integer`` Empty target column to be used with
-         :doc:`pgr_createTopology` function
+:source: ``integer`` Empty source column
+:target: ``integer`` Empty target column
 :the geom: ``geometry`` Geometry column of the noded network
 
 Examples
@@ -234,7 +232,6 @@ See Also
 -------------------------------------------------------------------------------
 
 :doc:`topology-functions` for an overview of a topology for routing algorithms.
-:doc:`pgr_createTopology` to create a topology based on the geometry.
 
 .. rubric:: Indices and tables