Updating documentation main (#2349)

* [restrictions] id of a restriction is not necesary * [allpairs][docqueries] porting and adjusting queries * [allpairs][doc] porting and adjusting documentation * [alpha_shape][docqueries] porting and adjusting queries * [alpha_shape][doc] porting and adjusting documentation * [astar][docqueries] porting and adjusting queries * [astar][doc] porting and adjusting documentation * [bdAstar][docqueries] porting and adjusting queries * [bdAstar][doc] porting and adjusting documentation * [bdDijkstra][docqueries] porting and adjusting queries * [bdDijkstra][doc] porting and adjusting documentation * [bellman_ford][docqueries] porting and adjusting queries * [bellman_ford][doc] porting and adjusting documentation * [breadthFirstSearch][docqueries] porting and adjusting queries * [breadthFirstSearch][doc] porting and adjusting documentation * [chinese][docqueries] porting and adjusting queries * [chinese][doc] porting and adjusting documentation * [coloring][docqueries] porting and adjusting queries * [coloring][doc] porting and adjusting documentation * [components][docqueries] porting and adjusting queries * [components][doc] porting and adjusting documentation * [contraction][docqueries] porting and adjusting queries * [contraction][doc] porting and adjusting documentation * [dagShortestPath][docqueries] porting and adjusting queries * [dagShortestPath][doc] porting and adjusting documentation * [dijkstra][docqueries] porting and adjusting queries * [dijkstra][doc] porting and adjusting documentation * [dominator][docqueries] porting and adjusting queries * [dominator][doc] porting and adjusting documentation * [driving_distance][docqueries] porting and adjusting queries * [driving_distance][doc] porting and adjusting documentation * [ksp][docqueries] porting and adjusting queries * [ksp][doc] porting and adjusting documentation * [lineGraph][docqueries] porting and adjusting queries * [lineGraph][doc] porting and adjusting documentation * [max_flow][docqueries] porting and adjusting queries * [max_flow][doc] porting and adjusting documentation * [mincut][docqueries] porting and adjusting queries * [mincut][doc] porting and adjusting documentation * [pickDeliver][docqueries] porting and adjusting queries * [pickDeliver][doc] porting and adjusting documentation * [planar][docqueries] porting and adjusting queries * [planar][doc] porting and adjusting documentation * [spanningTree][docqueries] porting and adjusting queries * [spanningTree][doc] porting and adjusting documentation * [src][docqueries] porting and adjusting queries * [src][doc] porting and adjusting documentation * [topologicalSort][docqueries] porting and adjusting queries * [topologicalSort][doc] porting and adjusting documentation * [topology][docqueries] porting and adjusting queries * [topology][doc] porting and adjusting documentation * [transitiveClosure][docqueries] porting and adjusting queries * [transitiveClosure][doc] porting and adjusting documentation * [traversal][docqueries] porting and adjusting queries * [traversal][doc] porting and adjusting documentation * [trsp][docqueries] porting and adjusting queries * [trsp][doc] porting and adjusting documentation * [tsp][docqueries] porting and adjusting queries * [tsp][doc] porting and adjusting documentation * [version][doc] porting and adjusting documentation * [vrp_basic][doc] porting and adjusting documentation * [withPoints][docqueries] porting and adjusting queries * [withPoints][doc] porting and adjusting documentation * [locale] updating the pot files * [locale][en] updating the english po files * [locale][es] updating the spanish translations files * [lint][docqueries] removing unused files * [sampledata] updating the sample data * [tools][translation] adjusting to weblate * [doc] updating some images, ignored links etc * [lint][doc] removing unused files * [doc] ignoring github failing link * [doc][locale][NEWS] updating release notes & news about this changes
pgRouting · Jul 6, 2022 · 2721bee · 2721bee
1 parent 1d4f0a5
commit 2721bee
Show file tree

Hide file tree

Showing 768 changed files with 105,133 additions and 79,662 deletions.
diff --git a/NEWS b/NEWS
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -236,7 +236,7 @@ if (LOCALE)
         "${PGR_DOCUMENTATION_SOURCE_DIR}"
         "${CMAKE_SOURCE_DIR}/locale/pot"
 
-        COMMAND sphinx-intl update -d ${CMAKE_SOURCE_DIR}/locale -l en > locale_changes.txt
+        COMMAND sphinx-intl update -d ${CMAKE_SOURCE_DIR}/locale -l en,es > locale_changes.txt
     #COMMAND sphinx-intl update -p ${CMAKE_SOURCE_DIR}/locale/pot -d ${CMAKE_SOURCE_DIR}/locale --language=${SPHINXINTL_LANGUAGE}
     #COMMAND sphinx-intl update-txconfig-resources --locale-dir ${CMAKE_SOURCE_DIR}/locale --pot-dir ${CMAKE_SOURCE_DIR}/locale/pot --transifex-project-name pgrouting
 

diff --git a/doc/_static/custom.css b/doc/_static/custom.css
@@ -13,3 +13,8 @@ div.content-wrapper {
 div.topic {
         border: none;
 }
+
+code.literal {
+    color: #404040;
+    background-color: #fbfbfb;
+}
diff --git a/doc/allpairs/allpairs-family.rst b/doc/allpairs/allpairs-family.rst
@@ -41,6 +41,81 @@ The following functions work on all vertices pair combinations
     pgr_floydWarshall
     pgr_johnson
 
+Introduction
+-------------------------------------------------------------------------------
+
+.. characteristics_start
+
+The main characteristics are:
+
+- It does not return a path.
+- Returns the sum of the costs of the shortest path for each pair of nodes in
+  the graph.
+- Process is done only on edges with positive costs.
+- Boost returns a :math:`V \times V` matrix, where the infinity values.
+  Represent the distance between vertices for which there is no path.
+
+  - We return only the non infinity values in form of a set of `(start_vid,
+    end_vid, agg_cost)`.
+
+- Let be the case the values returned are stored in a table, so the unique index
+  would be the pair: `(start_vid, end_vid)`.
+
+- For the undirected graph, the results are symmetric.
+
+  - The  `agg_cost` of `(u, v)` is the same as for `(v, u)`.
+
+- When  `start_vid` = `end_vid`, the `agg_cost` = 0.
+
+- **Recommended, use a bounding box of no more than 3500 edges.**
+
+.. characteristics_end
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. edges_start
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - `Edges SQL`_
+     - ``TEXT``
+     -
+     - `Edges SQL`_ as described below.
+
+.. edges_end
+
+Optional parameters
+...............................................................................
+
+.. include:: dijkstra-family.rst
+    :start-after: dijkstra_optionals_start
+    :end-before: dijkstra_optionals_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: no_id_edges_sql_start
+    :end-before: no_id_edges_sql_end
+
+Result Columns
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+    :start-after: return_cost_start
+    :end-before: return_cost_end
+
 
 Performance
 ------------------------------------------------------------------------------
@@ -57,15 +132,16 @@ Data
 
 The following data was used
 
-.. code-block:: none
+.. parsed-literal::
 
     BBOX="-122.8,45.4,-122.5,45.6"
-    wget --progress=dot:mega -O "sampledata.osm" "https://www.overpass-api.de/api/xapi?*[bbox=${BBOX}][@meta]"
+    wget --progress=dot:mega -O "sampledata.osm" \
+         "https://www.overpass-api.de/api/xapi?*[bbox=${BBOX}][@meta]"
 
 
 Data processing was done with osm2pgrouting-alpha
 
-.. code-block:: none
+.. parsed-literal::
 
     createdb portland
     psql -c "create extension postgis" portland
@@ -85,13 +161,15 @@ The density of the passed graph is extremely low.
 For each <SIZE> 30 tests were executed to get the average
 The tested query is:
 
-.. code-block:: none
+.. parsed-literal::
 
      SELECT count(*) FROM pgr_floydWarshall(
-        'SELECT gid as id, source, target, cost, reverse_cost FROM ways where id <=  <SIZE>');
+        'SELECT gid as id, source, target, cost, reverse_cost
+         FROM ways where id <=  <SIZE>');
 
      SELECT count(*) FROM pgr_johnson(
-        'SELECT gid as id, source, target, cost, reverse_cost FROM ways where id <=  <SIZE>');
+        'SELECT gid as id, source, target, cost, reverse_cost
+         FROM ways where id <=  <SIZE>');
 
 The results of this tests are presented as:
 
@@ -136,16 +214,20 @@ The density of the passed graph higher than of the Test One.
 For each <SIZE> 30 tests were executed to get the average
 The tested edge query is:
 
-.. code-block:: none
+.. parsed-literal::
 
     WITH
-        buffer AS (SELECT ST_Buffer(ST_Centroid(ST_Extent(the_geom)), SIZE) AS geom FROM ways),
-        bbox AS (SELECT ST_Envelope(ST_Extent(geom)) as box from buffer)
-    SELECT gid as id, source, target, cost, reverse_cost FROM ways where the_geom && (SELECT box from bbox);
+    buffer AS (
+      SELECT ST_Buffer(ST_Centroid(ST_Extent(the_geom)), SIZE) AS geom
+      FROM ways),
+    bbox AS (
+      SELECT ST_Envelope(ST_Extent(geom)) as box FROM buffer)
+    SELECT gid as id, source, target, cost, reverse_cost
+    FROM ways where the_geom && (SELECT box from bbox);
 
 The tested queries
 
-.. code-block:: none
+.. parsed-literal::
 
     SELECT count(*) FROM pgr_floydWarshall(<edge query>)
     SELECT count(*) FROM pgr_johnson(<edge query>)
@@ -188,7 +270,8 @@ See Also
 
 * :doc:`pgr_johnson`
 * :doc:`pgr_floydWarshall`
-* `Boost floyd-Warshall <https://www.boost.org/libs/graph/doc/floyd_warshall_shortest.html>`_ algorithm
+* Boost `floyd-Warshall
+  <https://www.boost.org/libs/graph/doc/floyd_warshall_shortest.html>`__
 
 .. rubric:: Indices and tables
 

diff --git a/doc/allpairs/pgr_floydWarshall.rst b/doc/allpairs/pgr_floydWarshall.rst
@@ -24,11 +24,11 @@
   `2.1 <https://docs.pgrouting.org/2.1/en/src/apsp_warshall/doc/index.html>`__
   `2.0 <https://docs.pgrouting.org/2.0/en/src/apsp_warshall/doc/index.html>`__
 
-pgr_floydWarshall
+``pgr_floydWarshall``
 ===============================================================================
 
-``pgr_floydWarshall`` - Returns the sum of the costs of the shortest path for each
-pair of nodes in the graph using Floyd-Warshall algorithm.
+``pgr_floydWarshall`` - Returns the sum of the costs of the shortest path for
+each pair of nodes in the graph using Floyd-Warshall algorithm.
 
 .. figure:: images/boost-inside.jpeg
    :target: https://www.boost.org/libs/graph/doc/floyd_warshall_shortest.html
@@ -46,87 +46,54 @@ pair of nodes in the graph using Floyd-Warshall algorithm.
 
   * **Official** function
 
-
 Description
 -------------------------------------------------------------------------------
 
-The Floyd-Warshall algorithm, also known as Floyd's algorithm,
-is a good choice to calculate the sum of the costs of the shortest path for each
-pair of nodes in the graph, for *dense graphs*. We use Boost's
-implementation which runs in :math:`\Theta(V^3)` time,
-
-The main characteristics are:
-  - It does not return a path.
-  - Returns the sum of the costs of the shortest path for each pair of nodes in the graph.
-  - Process is done only on edges with positive costs.
-  - Boost returns a :math:`V \times V` matrix, where the infinity values.
-    Represent the distance between vertices for which there is no path.
-
-    - We return only the non infinity values in form of a set of `(start_vid, end_vid, agg_cost)`.
-
-  - Let be the case the values returned are stored in a table, so the unique index would be the pair:
-    `(start_vid, end_vid)`.
-
-  - For the undirected graph, the results are symmetric.
-
-    - The  `agg_cost` of `(u, v)` is the same as for `(v, u)`.
+The Floyd-Warshall algorithm, also known as Floyd's algorithm, is a good choice
+to calculate the sum of the costs of the shortest path for each pair of nodes in
+the graph, for *dense graphs*.
+We use Boost's implementation which runs in :math:`\Theta(V^3)` time,
 
-  - When  `start_vid` = `end_vid`, the `agg_cost` = 0.
-
-  - **Recommended, use a bounding box of no more than 3500 edges.**
+.. include:: allpairs-family.rst
+   :start-after: characteristics_start
+   :end-before: characteristics_end
 
 Signatures
 -------------------------------------------------------------------------------
 
 .. rubric:: Summary
 
-.. code-block:: none
-
-    pgr floydWarshall(edges_sql [, directed])
-    RETURNS SET OF (start_vid, end_vid,  agg_cost)
-    OR EMPTY SET
-
-.. rubric:: Using defaults
-
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_floydWarshall(edges_sql)
-    RETURNS SET OF (start_vid, end_vid,  agg_cost)
+    pgr floydWarshall(`Edges SQL`_ [, directed])
+    RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
-:Example 1: For vertices :math:`\{1, 2, 3, 4\}` on a **directed** graph
+:Example: For a directed subgraph with edges :math:`\{1, 2, 3, 4\}`.
 
 .. literalinclude:: doc-floydWarshall.queries
    :start-after: -- q1
    :end-before: -- q2
 
-Complete Signature
-...............................................................................
-
-.. code-block:: none
+Parameters
+-------------------------------------------------------------------------------
 
-    pgr_floydWarshall(edges_sql [, directed])
-    RETURNS SET OF (start_vid, end_vid,  agg_cost)
-    OR EMPTY SET
+.. include:: allpairs-family.rst
+    :start-after: edges_start
+    :end-before: edges_end
 
-:Example 2: For vertices :math:`\{1, 2, 3, 4\}` on an **undirected** graph
+Optional parameters
+...............................................................................
 
-.. literalinclude:: doc-floydWarshall.queries
-   :start-after: -- q2
-   :end-before: -- q3
+.. include:: dijkstra-family.rst
+    :start-after: dijkstra_optionals_start
+    :end-before: dijkstra_optionals_end
 
-Parameters
+Inner Queries
 -------------------------------------------------------------------------------
 
-============= ============= =================================================
-Parameter     Type          Description
-============= ============= =================================================
-**edges_sql** ``TEXT``      SQL query as described above.
-**directed**  ``BOOLEAN``   (optional) Default is true (is directed). When set to false the graph is considered as Undirected
-============= ============= =================================================
-
-Inner query
--------------------------------------------------------------------------------
+Edges SQL
+...............................................................................
 
 .. include:: pgRouting-concepts.rst
     :start-after: no_id_edges_sql_start
@@ -137,23 +104,19 @@ Result Columns
 
 Returns set of ``(start_vid, end_vid, agg_cost)``
 
-============= ============= =================================================
-Column        Type          Description
-============= ============= =================================================
-**start_vid** ``BIGINT``    Identifier of the starting vertex.
-**end_vid**   ``BIGINT``    Identifier of the ending vertex.
-**agg_cost**  ``FLOAT``     Total cost from ``start_vid`` to ``end_vid``.
-============= ============= =================================================
+.. include:: pgRouting-concepts.rst
+    :start-after: return_cost_start
+    :end-before: return_cost_end
 
 See Also
 -------------------------------------------------------------------------------
 
 * :doc:`pgr_johnson`
-* `Boost floyd-Warshall <https://www.boost.org/libs/graph/doc/floyd_warshall_shortest.html>`_ algorithm
+* Boost `floyd-Warshall
+  <https://www.boost.org/libs/graph/doc/floyd_warshall_shortest.html>`_
 * Queries uses the :doc:`sampledata` network.
 
 .. rubric:: Indices and tables
 
 * :ref:`genindex`
 * :ref:`search`
-