def main():
'''Generates a python api documentation website.'''
if FileHandler('documentation').is_directory():
current_working_directory = FileHandler()
index_file = FileHandler('documentation/source/index.rst')
modules_to_document = '\ninit'
FileHandler(
location='%sinit.rst' % index_file.directory.path
).content = (
(79 * '=') + '\n{name}\n' + (79 * '=') + '\n\n.. automodule::' +
' {name}\n :members:'
).format(name=current_working_directory.name)
for file in FileHandler():
if Module.is_package(file.path):
modules_to_document += '\n %s' % file.name
FileHandler(location='%s%s.rst' % (
index_file.directory.path, file.name
)).content = (
(79 * '=') + '\n{name}.{package}\n' +
(79 * '=') + '\n\n.. automodule:: {name}.{package}\n'
' :members:'
).format(
name=current_working_directory.name, package=file.name)
for module in __get_all_modules__(file.path):
modules_to_document += '\n %s.%s' % (file.name, module)
FileHandler(location='%s%s.%s.rst' % (
index_file.directory.path, file.name, module
)).content = (
(79 * '=') + '\n{name}.{package}.{module}\n' +
(79 * '=') + '\n\n.. automodule:: {name}.{package}.'
'{module}\n :members:'
).format(
name=current_working_directory.name,
package=file.name, module=module)
index_file.content = regularExpression.compile(
'\n ([a-z][a-zA-Z]+\n)+$', regularExpression.DOTALL
).sub(modules_to_document, index_file.content)
Platform.run('/usr/bin/env git add --all', error=False, log=True)
FileHandler('documentation').change_working_directory()
makefile = FileHandler('Makefile')
# # python3.5 FileHandler('MakefilePython3').copy(makefile)
FileHandler('MakefilePython2').copy(makefile)
Platform.run(
command='make html', native_shell=True, error=False, log=True)
makefile.remove_file()
FileHandler('build/html').path = '../apiDocumentation'
FileHandler('build').remove_deep()
class Buffer(Class, LoggingStreamHandler):
'''
This class represents a layer for writing and reading to an output \
buffer realized as file, queue or variable.
**file** - a file path or file handler to use as \
buffer
**queue** - a queue object to use as buffer
**support_multiprocessing** - indicates whether buffer read and write \
requests should be multiprocessing save
Examples:
>>> buffer = Buffer(file=__test_folder__.path + 'Buffer')
>>> buffer.clear() # doctest: +ELLIPSIS
'...'
>>> print('hans', file=buffer, end='+')
>>> buffer.content
'hans+'
'''
# region dynamic methods
# # region public
# # # region special
@JointPoint
# # python3.5
# # def __init__(
# # self: Self, file=None, queue=None, support_multiprocessing=False
# # ) -> None:
def __init__(
self, file=None, queue=None, support_multiprocessing=False,
force_string=False
):
# #
'''
Saves the file path in the current instance. If "file" is "None" \
an instance variable is used as buffer.
Examples:
>>> Buffer(
... file=__test_folder__.path + '__init__'
... ).file # doctest: +ELLIPSIS
Object of "Handler" with path "...__init__" ...
>>> Buffer(
... queue=True, support_multiprocessing=True
... ).queue # doctest: +ELLIPSIS
<multiprocessing.queues.Queue object at ...>
'''
# # python3.5 pass
self.force_string = force_string
'''Saves the last written input.'''
self.last_written = ''
if support_multiprocessing:
self._lock = multiprocessing.Lock()
'''Saves the file handler instance for writing content into.'''
self.file = None
'''Saves the queue instance for writing content into.'''
self.queue = None
if queue is not None:
self.queue = native_queue.Queue()
if support_multiprocessing:
self.queue = multiprocessing.Queue()
if(builtins.isinstance(queue, native_queue.Queue) or
support_multiprocessing and
builtins.isinstance(queue, multiprocessing.queues.Queue)):
self.queue = queue
elif file is not None:
self.file = FileHandler(location=file)
'''
A lock object to guarantee that no other thread read from buffer \
during truncating or writing.
'''
self._lock = threading.Lock()
'''Saves the current buffer content.'''
# # python3.5
# # self._content = ''
self._content = builtins.str() if self.force_string else ''
# #
@JointPoint
# # python3.5 def __repr__(self: Self) -> builtins.str:
def __repr__(self):
'''
Invokes if this object should describe itself by a string.
Examples:
>>> repr(Buffer())
'Object of "Buffer" (memory buffered) with content "".'
>>> buffer = Buffer(file=__test_folder__.path + '__repr__')
>>> buffer.write('hans') # doctest: +ELLIPSIS
Object of "Buffer" (file buffered with "...__repr__" (type: file...
>>> repr(Buffer(queue=True))
'Object of "Buffer" (queue buffered) with content "".'
>>> repr(Buffer(queue=native_queue.Queue()))
'Object of "Buffer" (queue buffered) with content "".'
'''
buffer_type = 'memory'
type_addition = ''
if self.file:
buffer_type = 'file'
type_addition = ' with "%s"' % builtins.repr(self.file)
elif self.queue:
buffer_type = 'queue'
# # python3.5
# # pass
if self.force_string:
return (
'Object of "{class_name}" ({type} buffered{type_addition})'
' with content "{content}".'.format(
class_name=self.__class__.__name__,
type=buffer_type, type_addition=type_addition,
content=convert_to_unicode(self.content)))
# #
return (
'Object of "{class_name}" ({type} buffered{type_addition}) '
'with content "{content}".'.format(
class_name=self.__class__.__name__, type=buffer_type,
type_addition=type_addition, content=self.content))
@JointPoint
# # python3.5 def __str__(self: Self) -> builtins.str:
def __str__(self):
'''
Invokes if this object is tried to interpreted as string.
Examples:
>>> str(Buffer().write('test'))
'test'
'''
return self.content
@JointPoint
# # python3.5 def __bool__(self: Self) -> builtins.bool:
def __nonzero__(self):
'''
Invokes if this object is tried to interpreted as boolean.
Examples:
>>> bool(Buffer().write('test'))
True
>>> bool(Buffer())
False
'''
return builtins.bool(self.content)
# # # endregion
# # endregion
# # region getter
@JointPoint
# # python3.5 def get_content(self: Self) -> builtins.str:
def get_content(self):
'''
Getter for the current content.
Examples:
>>> Buffer().write('test').content
'test'
>>> Buffer(queue=True).write('test').content
'test'
'''
with self._lock:
if self.file is not None:
self._content = self.file.content
elif self.queue:
self._content = ''
temp_buffer = []
while not self.queue.empty():
# # python3.5
# # temp_buffer.append(self.queue.get())
temp_buffer.append(convert_to_unicode(
self.queue.get()))
# #
self._content += temp_buffer[-1]
for content in temp_buffer:
self.queue.put(content)
# # python3.5
# # pass
if self.force_string and builtins.isinstance(
self._content, builtins.unicode
):
self._content = convert_to_string(self._content)
# #
return self._content
# # endregion
@JointPoint
# # python3.5 def write(self: Self, content: builtins.str) -> Self:
def write(self, content):
'''
Writes content to the current output buffer file. If the current \
given file "Buffer.file" doesn't exists it will be created.
**content** - content to write into current buffer instance
Examples:
>>> buffer = Buffer(file=__test_folder__.path + 'write')
>>> buffer.clear() # doctest: +ELLIPSIS
'...'
>>> buffer.write('hans') # doctest: +ELLIPSIS
Object of "Buffer" (file buffered with "...write...nt "hans".
>>> buffer.content
'hans'
>>> buffer = Buffer()
>>> buffer.write('hans')
Object of "Buffer" (memory buffered) with content "hans".
>>> buffer.content
'hans'
'''
# # python3.5
# # pass
if self.force_string and builtins.isinstance(
content, builtins.unicode
):
content = convert_to_string(content)
# #
with self._lock:
self.last_written = content
if self.file is not None:
self.file.content += self.last_written
elif self.queue:
self.queue.put(self.last_written)
else:
self._content += self.last_written
return self
@JointPoint
# # python3.5 def flush(self: Self) -> Self:
def flush(self):
'''
Flush methods usually called to guarantee that all objects putted \
to "write()" are materialized on their provided media. This \
implementation exists only for compatibility reasons.
Examples:
>>> Buffer().flush()
Object of "Buffer" (memory buffered) with content "".
'''
return self
@JointPoint
# # python3.5 def clear(self: Self, delete=True) -> builtins.str:
def clear(self, delete=True):
'''
Removes the current output buffer content.
**delete** - indicates whether a file buffer should be deleted or \
truncated
Examples:
>>> buffer = Buffer(file=__test_folder__.path + 'clear')
>>> buffer.clear() # doctest: +ELLIPSIS
'...'
>>> buffer.write('hans') # doctest: +ELLIPSIS
Objec...(file buffered with "...clear...with content "hans".
>>> buffer.clear(False)
'hans'
>>> buffer.content
''
>>> buffer = Buffer()
>>> buffer.write('hans')
Object of "Buffer" (memory buffered) with content "hans".
>>> buffer.clear()
'hans'
>>> buffer.content
''
>>> buffer = Buffer(queue=True)
>>> buffer.clear()
''
>>> buffer.write('hans')
Object of "Buffer" (queue buffered) with content "hans".
>>> buffer.write('hans')
Object of "Buffer" (queue buffered) with content "hanshans".
>>> buffer.clear()
'hanshans'
>>> buffer.content
''
'''
with self._lock:
if self.file is not None:
content = self.file.content
if delete:
self.file.remove_file()
else:
self.file.content = ''
elif self.queue:
content = ''
while not self.queue.empty():
content += self.queue.get()
else:
content = self._content
self._content = ''
# # python3.5
# # pass
if self.force_string:
self._content = builtins.str()
content = convert_to_string(content)
# #
return content
def generate_and_push_new_documentation_page(
temporary_documentation_folder,
distribution_bundle_file,
has_api_documentation,
temporary_documentation_node_modules_directory
):
# #
'''
Renders a new index.html file and copies new assets to generate a new \
documentation homepage.
'''
global BUILD_DOCUMENTATION_PAGE_COMMAND
__logger__.info('Update documentation design.')
if distribution_bundle_file:
new_distribution_bundle_file = FileHandler(location='%s%s%s' % (
temporary_documentation_folder.path, DOCUMENTATION_BUILD_PATH,
DISTRIBUTION_BUNDLE_FILE_PATH))
new_distribution_bundle_file.directory.make_directories()
distribution_bundle_file.path = new_distribution_bundle_file
new_distribution_bundle_directory = FileHandler(location='%s%s%s' % (
temporary_documentation_folder.path, DOCUMENTATION_BUILD_PATH,
DISTRIBUTION_BUNDLE_DIRECTORY_PATH))
new_distribution_bundle_directory.make_directories()
zipfile.ZipFile(distribution_bundle_file.path).extractall(
new_distribution_bundle_directory.path)
favicon = FileHandler(location='favicon.png')
if favicon:
favicon.copy(target='%s/source/image/favicon.ico' %
temporary_documentation_folder.path)
parameter = builtins.dict(builtins.map(lambda item: (
String(item[0]).camel_case_to_delimited.content.upper(), item[1]
), SCOPE.get('documentationWebsite', {}).items()))
if 'TAGLINE' not in parameter and 'description' in SCOPE:
parameter['TAGLINE'] = SCOPE['description']
if 'NAME' not in parameter and 'name' in SCOPE:
parameter['NAME'] = SCOPE['name']
__logger__.debug('Found parameter "%s".', json.dumps(parameter))
api_documentation_path = None
if has_api_documentation:
api_documentation_path = '%s%s' % (
API_DOCUMENTATION_PATH[1], API_DOCUMENTATION_PATH_SUFFIX)
if not FileHandler(location='%s%s' % (
FileHandler().path, api_documentation_path
)).is_directory():
api_documentation_path = API_DOCUMENTATION_PATH[1]
parameter.update({
'CONTENT': CONTENT,
'CONTENT_FILE_PATH': None,
'RENDER_CONTENT': False,
'API_DOCUMENTATION_PATH': api_documentation_path,
'DISTRIBUTION_BUNDLE_FILE_PATH': DISTRIBUTION_BUNDLE_FILE_PATH if (
distribution_bundle_file and
distribution_bundle_file.is_file()
) else None
})
# # python3.5
# # parameter = Dictionary(parameter).convert(
# # value_wrapper=lambda key, value: value.replace(
# # '!', '#%%%#'
# # ) if builtins.isinstance(value, builtins.str) else value
# # ).content
parameter = Dictionary(parameter).convert(
value_wrapper=lambda key, value: value.replace(
'!', '#%%%#'
) if builtins.isinstance(value, builtins.unicode) else value
).content
# #
if __logger__.isEnabledFor(logging.DEBUG):
BUILD_DOCUMENTATION_PAGE_COMMAND = \
BUILD_DOCUMENTATION_PAGE_COMMAND[:-1] + [
'-debug'
] + BUILD_DOCUMENTATION_PAGE_COMMAND[-1:]
serialized_parameter = json.dumps(parameter)
parameter_file = FileHandler(location=make_secure_temporary_file('.json')[
1])
parameter_file.content = \
BUILD_DOCUMENTATION_PAGE_PARAMETER_TEMPLATE.format(
serializedParameter=serialized_parameter, **SCOPE)
for index, command in builtins.enumerate(BUILD_DOCUMENTATION_PAGE_COMMAND):
BUILD_DOCUMENTATION_PAGE_COMMAND[index] = \
BUILD_DOCUMENTATION_PAGE_COMMAND[index].format(
serializedParameter=serialized_parameter,
parameterFilePath=parameter_file._path,
**SCOPE)
__logger__.debug('Use parameter "%s".', serialized_parameter)
__logger__.info('Run "%s".', ' '.join(BUILD_DOCUMENTATION_PAGE_COMMAND))
current_working_directory_backup = FileHandler()
temporary_documentation_folder.change_working_directory()
Platform.run(
command=BUILD_DOCUMENTATION_PAGE_COMMAND[0],
command_arguments=BUILD_DOCUMENTATION_PAGE_COMMAND[1:], error=False,
log=True)
current_working_directory_backup.change_working_directory()
parameter_file.remove_file()
for file in FileHandler():
if not (file in (temporary_documentation_folder, FileHandler(
location='.%s' % API_DOCUMENTATION_PATH[1]
)) or is_file_ignored(file)):
file.remove_deep()
documentation_build_folder = FileHandler(location='%s%s' % (
temporary_documentation_folder.path, DOCUMENTATION_BUILD_PATH
), must_exist=True)
documentation_build_folder.iterate_directory(
function=copy_repository_file, recursive=True,
source=documentation_build_folder, target=FileHandler())
if (Platform.run(
"/usr/bin/env sudo umount '%s'" %
temporary_documentation_node_modules_directory.path,
native_shell=True, error=False, log=True
)['return_code'] == 0):
temporary_documentation_folder.remove_deep()
Platform.run(
(
'/usr/bin/env git add --all',
'/usr/bin/env git commit --message "%s" --all' %
PROJECT_PAGE_COMMIT_MESSAGE,
'/usr/bin/env git push',
'/usr/bin/env git checkout master'
),
native_shell=True,
error=False,
log=True
)
