function.rst standard - pgRouting/pgrouting GitHub Wiki
<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. Not all sections are needed in all functions, so when it is compulsory to be included it will be indicated.
The last section of this file has the standard to copy/paste. Or you can copy/paste a suitable file from the documentation for your new function.
The order of the sections are part of the standard
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/
****************************************************************************
- Must be included
.. _pgr_function_name:
pgr_functionName
===============================================================================
- Must be included
- The first line is separated with underscores, the second line is the actual name capitalizing for clarity
Name
------------------------------------------------------------------------------
``pgr_functionName`` - <One line description>
- Must be included
- The <One line description> is the same as in src/<section>/doc/index.rst
Synopsis
------------------------------------------------------------------------------
.. code-block:: sql
type pgr_functionName([list of parameters])
-
Must be included
-
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
- Must be included
- 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.
- Must be included
- 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
- Optional
- The Prerequisites may include:
- Other pgr functions that help prepare the data
- Column naming of the input table
- 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 paragraph as needed.
Usage
-----------------------------------------------------------------------------
Coment of the usage may go here
.. code-block:: sql
select pgr_FunctionName('edge_table', 'POINT(2 0)'::geometry, 0.02);
- Optional
- Inline comments on the code block don't get translated so try to place comments before or after the code block.
- Have as many usages as you need.
- No results in this section.
Examples
-----------------------------------------------------------------------------
Coment of the example may go here
.. code-block:: sql
select pgr_FunctionName('edge_table', 'POINT(2 0)'::geometry, 0.02);
pgr_FunctionName
-------------------
1
(1 row)
Comment about the results may go here
The example(s) use the :ref:`sampledata` network.
- Must be included
-
The Example section must include results.
-
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:`sampledata` network.
-
If the example(s) use other data, the code for generating the data should be placed in the example.
-
If the pgr_function use pgr_otherFunction as a prerequisite, include an example of the prerequisite
See Also
-----------------------------------------------------------------------------
* :ref:`pgr_name_of_other_function` - <One line description>
* :ref:`pgr_information_pages`- <One line description>
* external link
- Must be included (at least one link)
- The <One line description> of the corresponding index.rst of the file referenced.
- The external link as usual: http://etc
.. rubric:: History
* Modified in version xx
* New in version xx
- Must be included
.. index::
single: pgr_functionName( list of [parameter type])
module: <module name>
.. rubric:: Indices and tables
* :ref:`genindex`
* :ref:`search`
- Must be included
..
****************************************************************************
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`` - <One line description>
Synopsis
------------------------------------------------------------------------------
.. code-block:: sql
type pgr_functionName([list of parameters])
Description
-----------------------------------------------------------------------------
Description goes here
.. 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.
Prerequisites
------------------------------------------------------------------------------
Preparation of the input data may go here
Usage
-----------------------------------------------------------------------------
Coment of the usage may go here
.. code-block:: sql
select pgr_FunctionName('edge_table', 'POINT(2 0)'::geometry, 0.02);
Examples
-----------------------------------------------------------------------------
Coment of the example may go here
.. code-block:: sql
select pgr_FunctionName('edge_table', 'POINT(2 0)'::geometry, 0.02);
pgr_FunctionName
-------------------
1
(1 row)
Comment about the results may go here
The example(s) use the :ref:`sampledata` network.
See Also
-----------------------------------------------------------------------------
* bullet list of links
.. rubric:: History
* bullet list of history
.. index::
single: pgr_functionName( list of [parameter type])
module: <module name>
.. rubric:: Indices and tables
* :ref:`genindex`
* :ref:`search`