:py:mod:`utility`
=================

.. py:module:: utility

.. autoapi-nested-parse::

   Helper functions.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   utility.convert_readme_to_html_docs
   utility.get_api_server_url_from_request
   utility.get_base_url_from_request
   utility.get_url_for_app_from_request



.. py:function:: convert_readme_to_html_docs(text, remove_first_heading=True, convert_mermaid_diagrams=True, exclude_sections=None)

   Take an application's README file and parse it
   or display in HTML documentation.

   Options:

   remove_first_heading: removes any first level headings ("#")
   convert_mermaid_diagrams: change ```mermaid``` blocks into HTML <div>s
   exclude_sections: Remove sections with headings in the list
   <exclude_sections>.


.. py:function:: get_api_server_url_from_request(request, scheme='http')

   Return the api server url given an instance of Request, <request>,
   and scheme, <scheme>.

   Scheme is required in case the original scheme is not forwarded
   correctly through proxies.

   Example returns:
    - http://localhost/v1/
    - https://service.srcdev.skao.int/api/v1

   .. note::

      - request.scope.get('root_path') returns either e.g. /v1 or /api/v1
      (if proxied)
      - request.base_url returns the full path up to and including the proxy b
      ase path (e.g. api)
      - request.app.url_path_for(function_name) returns the (sub)application
      path for a given function name
        (function_name)


.. py:function:: get_base_url_from_request(request, scheme='http')

   Return the base url given an instance of Request, <request>,
   and scheme, <scheme>.

   Scheme is required in case the original scheme is not forwarded
   correctly through proxies.

   Example returns:
    - http://localhost
    - https://service.srcdev.skao.int/api


.. py:function:: get_url_for_app_from_request(function_name, request, scheme='http')

   Return an url for a particular (sub)application's function name,
   <function_name>, given an instance of Request,
   <request>, and scheme, <scheme>.

   Scheme is required in case the original scheme is not
   forwarded correctly through proxies.

   .. rubric:: Examples

   - on localhost, function_name="add_site":
     http://localhost/v1/www/sites/add
   - in production, function_name="add_site":
     https://service.srcdev.skao.int/api/v1/www/sites/add

   .. note::

      - request.scope.get('root_path') returns
      either e.g. /v1 or /api/v1 (if proxied)
      - request.base_url returns the full path up to and
      including the proxy base path (e.g. api)
      - request.app.url_path_for(function_name) returns the
      (sub)application path for a given function name
        (function_name)