function.rst standard
<function>.rst for the pgRouting functions are located on
- src/<section>/doc/<function>.rst
- src/<section>/doc/<subdivision>/<function>.rst (when applicable)
The following is the standard of the structure for the <function>.rst files (including examples for the links and or code).
The general structure of the file is:
..
****************************************************************************
pgRouting Manual
Copyright(c) pgRouting Contributors
This documentation is licensed under a Creative Commons Attribution-Share
Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/
****************************************************************************
.. _pgr_function_name:
pgr_functionName
===============================================================================
The first line is separated with underscores, the second line is the actual name capitalizing for clarity
Name
------------------------------------------------------------------------------
``pgr_functionName`` - <One line description>
The <One line description> is the same as in src/<section>/doc/index.rst
Synopsis
------------------------------------------------------------------------------
.. code-block:: sql
type pgr_functionName([list of parameters])
-
As many lines as the function requieres.
-
The list of parameters separated by commas ",".
-
Use the Parameters naming standard.
-
Each parameter has the following structure:
type name[:=default]
Description
-----------------------------------------------------------------------------
Sentence(s) with the description of the Function which may include:
the use of the data inputs
expected results
- This description is what I call medium level: Use the parameter names to describe the functionality of the function. Not being too low (describing how its done) nor being too high (describing the theory behind it) The high level description can be placed on the corresponding index.rst
- If in the future the paragraph changes (like adding a puctiation mark) the whole translation is lost so by keeping the description 2/3 sentences long will facilitate the work for the translators
- Use as many paragraphs as needed.
.. rubric:: Parameters
The function accepts the following parameters:
:parameter: ``type`` <One line description as in the example bellow>.
:tol: ``float8`` The maximum search distance for an edge.
Comments on the preparation of the input data may go here.
The function returns:
:parameterName: ``type`` <One/two line description as in the example above>.
Comments on the interpretation of the results may go here.
.. index::
single: pgr_functionName( list of [parameter type])
module: <module name>
You can copy/paste an change things acordingly.
..
****************************************************************************
pgRouting Manual
Copyright(c) pgRouting Contributors
This documentation is licensed under a Creative Commons Attribution-Share
Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/
****************************************************************************
.. _pgr_function_name:
pgr_functionName
===============================================================================
Name
------------------------------------------------------------------------------
``pgr_functionName`` - <Same One line description as in index.rst>
Synopsis
------------------------------------------------------------------------------
.. code-block:: sql
type pgr_functionName( list of: [parameter type])
Description
-----------------------------------------------------------------------------
Description of the Function which may include:
how to setup data for the inputs
expected results
.. rubric:: Parameters
The function accepts the following parameters:
:parameter: ``type`` <One line description as in the example bellow>.
:tol: ``float8`` The maximum search distance for an edge.
Comments on the preparation of the input data may go here.
The function returns:
:parameterName: ``type`` <One/two line description as in the example above>.
Comments on the interpretation of the results may go here.
Prerequisites
------------------------------------------------------------------------------
Preparation of the input data may go here and may include:
Other pgr functions that help prepare the data
Column naming of the input table
Examples
-----------------------------------------------------------------------------
.. code-block:: sql
select pgr_pointtoedgenode('edge_table', 'POINT(2 0)'::geometry, 0.02);
pgr_pointtoedgenode
-------------------
1
(1 row)
The example uses the :ref:`sampledata` network.
See Also
-----------------------------------------------------------------------------
* :ref:`pgr_name_of_other_function` - <same one line comment as in the index.rst of the other function>
.. rubric:: History
* New in version 2.1.0
.. index::
single: pgr_functionName( list of [parameter type])
module: <module name>
