1 #============================================================================ 

     2 #Name        : sphinx_ext.py 

     3 #Part of     : Helium 

     4 

     5 #Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     6 #All rights reserved.

     7 #This component and the accompanying materials are made available

     8 #under the terms of the License "Eclipse Public License v1.0"

     9 #which accompanies this distribution, and is available

    10 #at the URL "http://www.eclipse.org/legal/epl-v10.html".

    11 #

    12 #Initial Contributors:

    13 #Nokia Corporation - initial contribution.

    14 #

    15 #Contributors:

    16 #

    17 #Description:

    18 #===============================================================================

    19 """ aids to creating the API documentation"""

    20 import os

    21 import re

    22 

    23 from docutils import nodes, utils

    24 from docutils.parsers.rst import directives

    25 

    26 import amara

    27 

    28 treecache = None

    29 

    30 def handle_hlm_role(role, rawtext, text, lineno, inliner,

    31                        options=None, content=None):

    32     """ Process a custom Helium ReStructuredText role to link to a target, property or macro. """

    33     if options == None:

    34         options = {}

    35     if content == None:

    36         content = []

    37     full_path_match = re.search(r"<document source=\"(.*?)\"", str(inliner.document))

    38     full_path = full_path_match.group(1)

    39     path_segment = full_path[full_path.index('\\doc\\') + 5:]

    40     dir_levels = path_segment.count('\\')

    41     (parent_type, parent_name) = get_root_element_name(text)

    42     messages = []

    43 #    f = open('docs.log', 'a')

    44     if parent_type != None and parent_name != None:

    45         href_text = text.replace('.', '-').lower()

    46 #        f.write(href_text + "\n")

    47         api_path_segment = 'api/helium/' + parent_type + '-' + parent_name  + '.html#' + href_text

    48         relative_path = ('../' * dir_levels) + api_path_segment

    49         api_doc_path = os.path.abspath(os.path.join(os.getcwd() + '/build/doc', api_path_segment))

    50         node = nodes.reference(text, utils.unescape(text), refuri=relative_path, **options)

    51 #        f.write(str(node) + "\n")

    52         node = nodes.literal(text, '', node, **options)

    53     else:

    54         messages.append(inliner.reporter.error(('Missing API doc for "%s".' % text), line=lineno))

    55         node = nodes.literal(text, utils.unescape(text))

    56 #    f.close()

    57     return [node], messages

    58 

    59 def get_root_element_name(text):

    60     global treecache

    61     if treecache == None:

    62         database_path = os.path.abspath(os.path.join(os.getcwd() + '/build', 'public_database.xml'))

    63         f = open(database_path)

    64         tree = amara.parse(f)

    65         

    66         treecache = {}

    67         for project in tree.antDatabase.project:

    68             for x in project.xml_children:

    69                 if hasattr(x, 'name'):

    70                     treecache[str(x.name)] = str(project.name)

    71                     

    72     if text in treecache:

    73         return ('project', treecache[text])

    74     return (None, None)

    75 

    76 roles = {'hlm-t': 'target',

    77          'hlm-p': 'property',

    78          'hlm-m': 'macro',}

    79 

    80 

    81 def setup(app):

    82     """ Register custom RST roles for linking Helium targets, properties and macros

    83     to the API documentation. """

    84     for role in roles.keys():

    85         app.add_role(role, handle_hlm_role)

    86     app.add_description_unit('property', 'ant-prop', 'pair: %s; property')

    87     app.add_description_unit('target', 'ant-target', 'pair: %s; target')

    88 

    89     

    90     

    91