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>
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 results may go here.
- Use the Parameters naming standard.
- If in the future the paragraph changes (like adding a puctiation mark) the whole translation is lost so by keeping the comments 2/3 sentences long will facilitate the work for the translators
- Use as many comments as needed.
Prerequisites
------------------------------------------------------------------------------
Preparation of the input data may go here
- The Prerequisites may include:
- Other pgr functions that help prepare the data
- Column naming of the input table
Examples
-----------------------------------------------------------------------------
Coment of the example may go here
.. code-block:: sql
select pgr_pointtoedgenode('edge_table', 'POINT(2 0)'::geometry, 0.02);
pgr_pointtoedgenode
-------------------
1
(1 row)
Comment about the results may go here
The example(s) use the :ref:`sampledata` network.
-
Inline comments on the code block don't get translated so try to place comments before or after the code block
-
Have as many examples as you need.
-
Usually the example(s) use the sample data network, if that is the case, the following line goes after the last example
The example(s) use the :ref:
sampledatanetwork. -
If the example(s) use other data, the code for generating the data should be placed in the example.
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>
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.
type name[:=default]
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>
