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.metainfo = metainfo
82  self.name = metainfo['name']
83  self.fancyname = metainfo['fancyname']
84  self.description = metainfo.get('description')
85  self.maintainers = utils.set_maintainers(metainfo.get('maintainer'), all_maintainers)
86  self.platforms = platforms
87  self.outputdir = self._set_outputdir(self.part_of_group)
88  self.href = '../' + self.outputdir.lower() + '/html/index.html'
89  self.path = metainfo['path']
90  self.srcdirs = utils.tolist(metainfo.get('public_source_dirs', ['src']))
91  self.docdir = utils.tolist(metainfo.get('public_doc_dir', ['docs']))
92  if 'public_example_dirs' in metainfo:
93  self.exampledirs = utils.tolist(metainfo.get('public_example_dirs', ['examples']))
94  else:
95  # backward compat
96  self.exampledirs = utils.tolist(metainfo.get('public_example_dir', ['examples']))
97  self.dependency_diagram = None
98  self.type = metainfo.get('type', '')
99  self.portingAid = metainfo.get('portingAid', False)
100  self.deprecated = metainfo.get('deprecated', False)
101  self.libraries = metainfo.get('libraries', [])
102  self.cmakename = metainfo.get('cmakename', '')
103  self.irc = metainfo.get('irc', self.product.irc)
104  self.mailinglist = metainfo.get('mailinglist', self.product.mailinglist)
105  self.repopath = utils.set_repopath(metainfo['repo_id'])
106 
107  def _extend_parent(self, metainfo, key, key_obj, default):
108  if key in metainfo:
109  return metainfo[key]
110  elif getattr(self.product, key_obj) is not None:
111  return getattr(self.product, key_obj)
112  else:
113  return default
114 
115  def _set_outputdir(self, grouped):
116  outputdir = self.name
117  if grouped:
118  outputdir = self.product.outputdir + '/' + outputdir
119  return outputdir.lower()
120 
121 
122 class Product(object):
123  """ Product
124  """
125 
126  # TODO: If no name and no group, it will fail !
127  def __init__(self, metainfo, all_maintainers):
128  """
129  Constructor of the Product object
130 
131  Args:
132  metainfo: (dict) dictionary describing a product
133  all_maintainers: (dict of dict) all possible maintainers, where the main key
134  is a username/unique pseudo, and the key is a dictionary of name,
135  email address. For example:
136  {
137  'username01': { 'name': 'Paul Developer', 'email': '[email protected]' },
138  'username02': { 'name': 'Marc Developer2', 'email': '[email protected]' }
139  }
140  would work.
141 
142  """
143 
144  self.metainfo = metainfo
145  self.parent = None
146  # if there is a group, the product is the group
147  # else the product is directly the library
148 
149  if 'group_info' in metainfo:
150  self.name = utils.serialize_name(metainfo['group_info'].get('name', metainfo.get('group')))
151  self.fancyname = metainfo['group_info'].get('fancyname', string.capwords(self.name))
152  self.description = metainfo['group_info'].get('description')
153  self.long_description = metainfo['group_info'].get('long_description', [])
154  self.maintainers = utils.set_maintainers(metainfo['group_info'].get('maintainer'),
155  all_maintainers)
156  self.platforms = metainfo['group_info'].get('platforms')
157  self.outputdir = self.name
158  self.href = self.outputdir + '/index.html'
159  self.logo_url_src = self._set_logo_src(metainfo['path'],
160  metainfo['group_info'])
161  self.logo_url = self._set_logo()
162  self.libraries = [] # We'll set this later
163  self.subgroups = [] # We'll set this later
164  self.irc = metainfo['group_info'].get('irc', 'kde-devel')
165  self.mailinglist = metainfo['group_info'].get('mailinglist', 'kde-devel')
166  self.subproducts = self._extract_subproducts(metainfo['group_info'])
167  self.part_of_group = True
168 
169  elif 'group' not in metainfo:
170  self.name = utils.serialize_name(metainfo['name'])
171  self.fancyname = metainfo['fancyname']
172  self.description = metainfo.get('description')
173  self.maintainers = utils.set_maintainers(metainfo.get('maintainer'), all_maintainers)
174  self.platforms = [x['name'] for x in metainfo.get('platforms', [{'name': None}])]
175  self.outputdir = self.name
176  self.href = self.outputdir + '/html/index.html'
177  self.logo_url_src = self._set_logo_src(metainfo['path'], metainfo)
178  self.logo_url = self._set_logo()
179  self.libraries = []
180  self.irc = None
181  self.mailinglist = None
182  self.part_of_group = False
183  else:
184  raise ValueError("I do not recognize a product in {}."
185  .format(metainfo['name']))
186 
187  def _extract_subproducts(self, groupinfo):
188  subproducts = []
189  if 'subgroups' in groupinfo:
190  for sg in groupinfo['subgroups']:
191  sg
192  if 'name' in sg:
193  subproducts.append(Subproduct(sg, self))
194  return subproducts
195 
196  def _set_logo(self):
197  if self.logo_url_src is not None:
198  filename, ext = os.path.splitext(self.logo_url_src)
199  return self.outputdir + '/' + self.name + ext
200  else:
201  return None
202 
203  def _set_logo_src(self, path, dct):
204  defined_not_found = False
205  if 'logo' in dct:
206  logo_url = os.path.join(path, dct['logo'])
207  if os.path.isfile(logo_url):
208  return logo_url
209  else:
210  defined_not_found = True
211 
212  logo_url = os.path.join(path, 'logo.png')
213  if os.path.isfile(logo_url):
214  if defined_not_found:
215  logging.warning("Defined {} logo file doesn't exist, set back to found logo.png"
216  .format(self.fancyname))
217  return logo_url
218 
219  if defined_not_found:
220  logging.warning("Defined {} logo file doesn't exist, set back to None"
221  .format(self.fancyname))
222 
223  return None
224 
225 class Subproduct(object):
226  """ Subproduct
227  """
228  def __init__(self, spinfo, product):
229  """
230  Constructor of the Subproduct object
231 
232  Args:
233  spinfo: (dict) description of the subproduct. It is not more than:
234  {
235  'name': 'Subproduct Name',
236  'description': 'This subproduct does this and that',
237  'order': 3, # this is optional
238  }
239  for example.
240  product: (Product) the product it is part of.
241  """
242  self.fancyname = spinfo['name']
243  self.name = utils.serialize_name(spinfo['name'])
244  self.description = spinfo.get('description')
245  self.order = spinfo.get('order', 99) # If no order, go to end
246  self.libraries = []
247  self.product = product
248  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:202
def __init__(self, metainfo, all_maintainers)
Constructor of the Product object.
Definition: models.py:148
def _set_logo_src(self, path, dct)
Definition: models.py:209
def _set_outputdir(self, grouped)
Definition: models.py:119
def _extract_subproducts(self, groupinfo)
Definition: models.py:193
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 26 2021 22:55:54 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.