KApiDox

models.py
1 # -*- coding: utf-8 -*-
2 #
3 # SPDX-FileCopyrightText: 2016 Olivier Churlaud <[email protected]>
4 #
5 # SPDX-License-Identifier: BSD-2-Clause
6 
7 import logging
8 import os.path
9 import string
10 from kapidox import utils
11 
12 ## @package kapidox.models
13 #
14 # Contains the classes representing the objects used by kapidox
15 #
16 
17 class Library(object):
18  """ Library
19  """
20 
21  def __init__(self, metainfo, products, platforms, all_maintainers):
22  """
23  Constructor of the Library object
24 
25  Args:
26  metainfo: (dict) dictionary describing a library
27  products: (list of Products) list of all already created products
28  platforms: (dict) dictionary of all platforms for which the library
29  is available, where the key is a platform and the value
30  is a restriction. For instance:
31  {
32  'Linux': '',
33  'Windows': 'Tested with Windows 10 only'
34  }
35  would work.
36  all_maintainers: (dict of dict) all possible maintainers, where the main key
37  is a username/unique pseudo, and the key is a dictionary of name,
38  email address. For example:
39  {
40  'username01': { 'name': 'Paul Developer', 'email': '[email protected]' },
41  'username02': { 'name': 'Marc Developer2', 'email': '[email protected]' }
42  }
43  would work.
44 
45  """
46  self.product = None
47  self.subproduct = None
48 
49  if 'group' in metainfo:
50  productname = metainfo['group']
51  self.part_of_group = True
52  else:
53  productname = metainfo['name']
54  self.part_of_group = False
55  if utils.serialize_name(productname) not in products:
56  productname = metainfo['name']
57  del metainfo['group']
58  products[utils.serialize_name(metainfo['name'])] = Product(metainfo, all_maintainers)
59  self.part_of_group = False
60  logging.warning("Group of {} not found: dropped.".format(metainfo['fancyname']))
61  self.product = products[utils.serialize_name(productname)]
62  if self.product is None:
63  raise ValueError("'{}' does not belong to a product."
64  .format(metainfo['name']))
65 
66  if 'subgroup' in metainfo and self.part_of_group:
67  for sp in self.product.subproducts:
68  if sp.name == utils.serialize_name(metainfo['subgroup']):
69  self.subproduct = sp
70  if self.subproduct is None:
71  logging.warning("Subgroup {} of library {} not documented, subgroup will be None"
72  .format(metainfo['subgroup'], metainfo['name']))
73 
74  if self.subproduct is not None:
75  self.parent = self.subproduct
76  self.subproduct.libraries.append(self)
77  else:
78  self.parent = self.product
79  self.product.libraries.append(self)
80 
81  self.name = metainfo['name']
82  self.fancyname = metainfo['fancyname']
83  self.description = metainfo.get('description')
84  self.maintainers = utils.set_maintainers(metainfo.get('maintainer'), all_maintainers)
85  self.platforms = platforms
86  self.outputdir = self._set_outputdir(self.part_of_group)
87  self.href = '../' + self.outputdir.lower() + '/html/index.html'
88  self.path = metainfo['path']
89  self.srcdirs = utils.tolist(metainfo.get('public_source_dirs', ['src']))
90  self.docdir = utils.tolist(metainfo.get('public_doc_dir', ['docs']))
91  if 'public_example_dirs' in metainfo:
92  self.exampledirs = utils.tolist(metainfo.get('public_example_dirs', ['examples']))
93  else:
94  # backward compat
95  self.exampledirs = utils.tolist(metainfo.get('public_example_dir', ['examples']))
96  self.dependency_diagram = None
97  self.type = metainfo.get('type', '')
98  self.portingAid = metainfo.get('portingAid', False)
99  self.deprecated = metainfo.get('deprecated', False)
100  self.libraries = metainfo.get('libraries', [])
101  self.cmakename = metainfo.get('cmakename', '')
102  self.irc = metainfo.get('irc', self.product.irc)
103  self.mailinglist = metainfo.get('mailinglist', self.product.mailinglist)
104  self.repopath = utils.set_repopath(metainfo['repo_id'])
105 
106  def _extend_parent(self, metainfo, key, key_obj, default):
107  if key in metainfo:
108  return metainfo[key]
109  elif getattr(self.product, key_obj) is not None:
110  return getattr(self.product, key_obj)
111  else:
112  return default
113 
114  def _set_outputdir(self, grouped):
115  outputdir = self.name
116  if grouped:
117  outputdir = self.product.outputdir + '/' + outputdir
118  return outputdir.lower()
119 
120 
121 class Product(object):
122  """ Product
123  """
124 
125  # TODO: If no name and no group, it will fail !
126  def __init__(self, metainfo, all_maintainers):
127  """
128  Constructor of the Product object
129 
130  Args:
131  metainfo: (dict) dictionary describing a product
132  all_maintainers: (dict of dict) all possible maintainers, where the main key
133  is a username/unique pseudo, and the key is a dictionary of name,
134  email address. For example:
135  {
136  'username01': { 'name': 'Paul Developer', 'email': '[email protected]' },
137  'username02': { 'name': 'Marc Developer2', 'email': '[email protected]' }
138  }
139  would work.
140 
141  """
142 
143  self.parent = None
144  # if there is a group, the product is the group
145  # else the product is directly the library
146 
147  if 'group_info' in metainfo:
148  self.name = utils.serialize_name(metainfo['group_info'].get('name', metainfo.get('group')))
149  self.fancyname = metainfo['group_info'].get('fancyname', string.capwords(self.name))
150  self.description = metainfo['group_info'].get('description')
151  self.long_description = metainfo['group_info'].get('long_description', [])
152  self.maintainers = utils.set_maintainers(metainfo['group_info'].get('maintainer'),
153  all_maintainers)
154  self.platforms = metainfo['group_info'].get('platforms')
155  self.outputdir = self.name
156  self.href = self.outputdir + '/index.html'
157  self.logo_url_src = self._set_logo_src(metainfo['path'],
158  metainfo['group_info'])
159  self.logo_url = self._set_logo()
160  self.libraries = [] # We'll set this later
161  self.subgroups = [] # We'll set this later
162  self.irc = metainfo['group_info'].get('irc', 'kde-devel')
163  self.mailinglist = metainfo['group_info'].get('mailinglist', 'kde-devel')
164  self.subproducts = self._extract_subproducts(metainfo['group_info'])
165  self.part_of_group = True
166 
167  elif 'group' not in metainfo:
168  self.name = utils.serialize_name(metainfo['name'])
169  self.fancyname = metainfo['fancyname']
170  self.description = metainfo.get('description')
171  self.maintainers = utils.set_maintainers(metainfo.get('maintainer'), all_maintainers)
172  self.platforms = [x['name'] for x in metainfo.get('platforms', [{'name': None}])]
173  self.outputdir = self.name
174  self.href = self.outputdir + '/html/index.html'
175  self.logo_url_src = self._set_logo_src(metainfo['path'], metainfo)
176  self.logo_url = self._set_logo()
177  self.libraries = []
178  self.irc = None
179  self.mailinglist = None
180  self.part_of_group = False
181  else:
182  raise ValueError("I do not recognize a product in {}."
183  .format(metainfo['name']))
184 
185  def _extract_subproducts(self, groupinfo):
186  subproducts = []
187  if 'subgroups' in groupinfo:
188  for sg in groupinfo['subgroups']:
189  sg
190  if 'name' in sg:
191  subproducts.append(Subproduct(sg, self))
192  return subproducts
193 
194  def _set_logo(self):
195  if self.logo_url_src is not None:
196  filename, ext = os.path.splitext(self.logo_url_src)
197  return self.outputdir + '/' + self.name + ext
198  else:
199  return None
200 
201  def _set_logo_src(self, path, dct):
202  defined_not_found = False
203  if 'logo' in dct:
204  logo_url = os.path.join(path, dct['logo'])
205  if os.path.isfile(logo_url):
206  return logo_url
207  else:
208  defined_not_found = True
209 
210  logo_url = os.path.join(path, 'logo.png')
211  if os.path.isfile(logo_url):
212  if defined_not_found:
213  logging.warning("Defined {} logo file doesn't exist, set back to found logo.png"
214  .format(self.fancyname))
215  return logo_url
216 
217  if defined_not_found:
218  logging.warning("Defined {} logo file doesn't exist, set back to None"
219  .format(self.fancyname))
220 
221  return None
222 
223 class Subproduct(object):
224  """ Subproduct
225  """
226  def __init__(self, spinfo, product):
227  """
228  Constructor of the Subproduct object
229 
230  Args:
231  spinfo: (dict) description of the subproduct. It is not more than:
232  {
233  'name': 'Subproduct Name',
234  'description': 'This subproduct does this and that',
235  'order': 3, # this is optional
236  }
237  for example.
238  product: (Product) the product it is part of.
239  """
240  self.fancyname = spinfo['name']
241  self.name = utils.serialize_name(spinfo['name'])
242  self.description = spinfo.get('description')
243  self.order = spinfo.get('order', 99) # If no order, go to end
244  self.libraries = []
245  self.product = product
246  self.parent = product
def __init__(self, metainfo, products, platforms, all_maintainers)
Constructor of the Library object.
Definition: models.py:49
def _set_logo(self)
Definition: models.py:200
def __init__(self, metainfo, all_maintainers)
Constructor of the Product object.
Definition: models.py:147
def _set_logo_src(self, path, dct)
Definition: models.py:207
def _set_outputdir(self, grouped)
Definition: models.py:118
def _extract_subproducts(self, groupinfo)
Definition: models.py:191
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Nov 30 2020 22:54:36 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.