def document_geom(geom):
    """
    Create a structured documentation for the geom

    It replaces `{usage}`, `{common_parameters}` and
    `{aesthetics}` with generated documentation.
    """
    # Dedented so that it lineups (in sphinx) with the part
    # generated parts when put together
    docstring = dedent(geom.__doc__)

    # usage
    signature = make_signature(geom.__name__,
                               geom.DEFAULT_PARAMS,
                               common_geom_params,
                               common_geom_param_values)
    usage = GEOM_SIGNATURE_TPL.format(signature=signature)

    # aesthetics
    contents = OrderedDict(('**{}**'.format(ae), '')
                           for ae in sorted(geom.REQUIRED_AES))
    if geom.DEFAULT_AES:
        d = geom.DEFAULT_AES.copy()
        d['group'] = ''  # All geoms understand the group aesthetic
        contents.update(sorted(d.items()))

    table = dict_to_table(('Aesthetic', 'Default value'), contents)
    aesthetics_table = AESTHETICS_TABLE_TPL.format(table=table)
    tpl = dedent(geom._aesthetics_doc.lstrip('\n'))
    aesthetics_doc = tpl.format(aesthetics_table=aesthetics_table)
    aesthetics_doc = indent(aesthetics_doc, ' '*4)

    # common_parameters
    d = geom.DEFAULT_PARAMS
    common_parameters = GEOM_PARAMS_TPL.format(
        default_stat=d['stat'],
        default_position=d['position'],
        default_na_rm=d['na_rm'],
        default_inherit_aes=d.get('inherit_aes', True),
        _aesthetics_doc=aesthetics_doc,
        **common_params_doc)

    docstring = docstring.replace('{usage}', usage)
    docstring = docstring.replace('{common_parameters}',
                                  common_parameters)
    geom.__doc__ = docstring
    return geom
def document_geom ( geom ) : docstring = dedent ( geom . __doc__ ) signature = make_signature ( geom . __name__ , geom . DEFAULT_PARAMS , common_geom_params , common_geom_param_values ) usage = GEOM_SIGNATURE_TPL . format ( signature = signature ) contents = OrderedDict ( ( '**{}**' . format ( ae ) , '' ) for ae in sorted ( geom . REQUIRED_AES ) ) if geom . DEFAULT_AES : d = geom . DEFAULT_AES . copy ( ) d [ 'group' ] = '' contents . update ( sorted ( d . items ( ) ) ) table = dict_to_table ( ( 'Aesthetic' , 'Default value' ) , contents ) aesthetics_table = AESTHETICS_TABLE_TPL . format ( table = table ) tpl = dedent ( geom . _aesthetics_doc . lstrip ( '\n' ) ) aesthetics_doc = tpl . format ( aesthetics_table = aesthetics_table ) aesthetics_doc = indent ( aesthetics_doc , ' ' * 4 ) d = geom . DEFAULT_PARAMS common_parameters = GEOM_PARAMS_TPL . format ( default_stat = d [ 'stat' ] , default_position = d [ 'position' ] , default_na_rm = d [ 'na_rm' ] , default_inherit_aes = d . get ( 'inherit_aes' , True ) , _aesthetics_doc = aesthetics_doc , ** common_params_doc ) docstring = docstring . replace ( '{usage}' , usage ) docstring = docstring . replace ( '{common_parameters}' , common_parameters ) geom . __doc__ = docstring return geom
Create a structured documentation for the geom

    It replaces `{usage}`, `{common_parameters}` and
    `{aesthetics}` with generated documentation.