thatscringebro/MementoMori
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Ajout du GUI

Browse Source
This commit is contained in:
thatscringebro
2022-08-08 16:31:52 -04:00
parent db362ccdca
commit abd15f28b6
851 changed files with 99957 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
kivy/tools/gallery.py Normal file
View File

@@ -0,0 +1,323 @@
''' Create rst documentation of the examples directory.
This uses screenshots in the screenshots_dir
(currently doc/sources/images/examples) along with source code and files
in the examples/ directory to create rst files in the generation_dir
(doc/sources/examples) gallery.rst, index.rst, and gen__*.rst
'''
import os
import re
from os.path import sep
from os.path import join as slash # just like that name better
from os.path import dirname, abspath
import kivy
from kivy.logger import Logger
import textwrap
# from here to the kivy top
base_dir = dirname(dirname(abspath(kivy.__file__)))
examples_dir = slash(base_dir, 'examples')
screenshots_dir = slash(base_dir, 'doc/sources/images/examples')
generation_dir = slash(base_dir, 'doc/sources/examples')
image_dir = "../images/examples/" # relative to generation_dir
gallery_filename = slash(generation_dir, 'gallery.rst')
# Info is a dict built up from
# straight filename information, more from reading the docstring,
# and more from parsing the description text. Errors are often
# shown by setting the key 'error' with the value being the error message.
#
# It doesn't quite meet the requirements for a class, but is a vocabulary
# word in this module.
def iter_filename_info(dir_name):
"""
Yield info (dict) of each matching screenshot found walking the
directory dir_name. A matching screenshot uses double underscores to
separate fields, i.e. path__to__filename__py.png as the screenshot for
examples/path/to/filename.py.
Files not ending with .png are ignored, others are either parsed or
yield an error.
Info fields 'dunder', 'dir', 'file', 'ext', 'source' if not 'error'
"""
pattern = re.compile(r'^((.+)__(.+)__([^-]+))\.png')
for t in os.walk(dir_name):
for filename in t[2]:
if filename.endswith('.png'):
m = pattern.match(filename)
if m is None:
yield {'error': 'png filename not following screenshot'
' pattern: {}'.format(filename)}
else:
d = m.group(2).replace('__', sep)
yield {'dunder': m.group(1),
'dir': d,
'file': m.group(3),
'ext': m.group(4),
'source': slash(d, m.group(3) + '.' + m.group(4))
}
def parse_docstring_info(text):
''' parse docstring from text (normal string with '\n's) and return an info
dict. A docstring should the first triple quoted string, have a title
followed by a line of equal signs, and then a description at
least one sentence long.
fields are 'docstring', 'title', and 'first_sentence' if not 'error'
'first_sentence' is a single line without newlines.
'''
q = '\"\"\"|\'\'\''
p = r'({})\s+([^\n]+)\s+\=+\s+(.*?)(\1)'.format(q)
m = re.search(p, text, re.S)
if m:
comment = m.group(3).replace('\n', ' ')
first_sentence = comment[:comment.find('.') + 1]
return {'docstring': m.group(0), 'title': m.group(2),
'description': m.group(3), 'first_sentence': first_sentence}
else:
return {'error': 'Did not find docstring with title at top of file.'}
def iter_docstring_info(dir_name):
''' Iterate over screenshots in directory, yield info from the file
name and initial parse of the docstring. Errors are logged, but
files with errors are skipped.
'''
for file_info in iter_filename_info(dir_name):
if 'error' in file_info:
Logger.error(file_info['error'])
continue
source = slash(examples_dir, file_info['dir'],
file_info['file'] + '.' + file_info['ext'])
if not os.path.exists(source):
Logger.error('Screen shot references source code that does '
'not exist: %s', source)
continue
with open(source) as f:
text = f.read()
docstring_info = parse_docstring_info(text)
if 'error' in docstring_info:
Logger.error(docstring_info['error'] + ' File: ' + source)
continue # don't want to show ugly entries
else:
file_info.update(docstring_info)
yield file_info
def enhance_info_description(info, line_length=79):
''' Using the info['description'], add fields to info.
info['files'] is the source filename and any filenames referenced by the
magic words in the description, e.g. 'the file xxx.py' or
'The image this.png'. These are as written in the description, do
not allow ../dir notation, and are relative to the source directory.
info['enhanced_description'] is the description, as an array of
paragraphs where each paragraph is an array of lines wrapped to width
line_length. This enhanced description include the rst links to
the files of info['files'].
'''
# make text a set of long lines, one per paragraph.
paragraphs = info['description'].split('\n\n')
lines = [
paragraph.replace('\n', '$newline$')
for paragraph in paragraphs
]
text = '\n'.join(lines)
info['files'] = [info['file'] + '.' + info['ext']]
regex = r'[tT]he (?:file|image) ([\w\/]+\.\w+)'
for name in re.findall(regex, text):
if name not in info['files']:
info['files'].append(name)
# add links where the files are referenced
folder = '_'.join(info['source'].split(sep)[:-1]) + '_'
text = re.sub(r'([tT]he (?:file|image) )([\w\/]+\.\w+)',
r'\1:ref:`\2 <$folder$\2>`', text)
text = text.replace('$folder$', folder)
# now break up text into array of paragraphs, each an array of lines.
lines = [line.replace('$newline$', '\n') for line in text.split('\n')]
paragraphs = [
textwrap.wrap(line, line_length)
# ignore wrapping if .. note:: or similar block
if not line.startswith(' ') else [line]
for line in lines
]
info['enhanced_description'] = paragraphs
def get_infos(dir_name):
''' return infos, an array info dicts for each matching screenshot in the
dir, sorted by source file name, and adding the field 'num' as he unique
order in this array of dicts'.
'''
infos = [i for i in iter_docstring_info(dir_name)]
infos.sort(key=lambda x: x['source'])
for num, info in enumerate(infos):
info['num'] = num
enhance_info_description(info)
return infos
def make_gallery_page(infos):
''' return string of the rst (Restructured Text) of the gallery page,
showing information on all screenshots found.
'''
gallery_top = '''
Gallery
-------
.. _Tutorials: ../tutorials-index.html
.. container:: title
This gallery lets you explore the many examples included with Kivy.
Click on any screenshot to see the code.
This gallery contains:
* Examples from the examples/ directory that show specific capabilities of
different libraries and features of Kivy.
* Demonstrations from the examples/demos/ directory that explore many of
Kivy's abilities.
There are more Kivy programs elsewhere:
* Tutorials_ walks through the development of complete Kivy applications.
* Unit tests found in the source code under the subdirectory kivy/tests/
can also be useful.
We hope your journey into learning Kivy is exciting and fun!
'''
output = [gallery_top]
for info in infos:
output.append(
"\n**{title}** (:doc:`{source}<gen__{dunder}>`)\n"
"\n{description}"
"\n.. image:: ../images/examples/{dunder}.png"
"\n :width: 216pt"
"\n :align: left"
"\n :target: gen__{dunder}.html".format(**info))
return "\n".join(output) + "\n"
def make_detail_page(info):
''' return str of the rst text for the detail page of the file in info. '''
def a(s=''):
''' append formatted s to output, which will be joined into lines '''
output.append(s.format(**info))
output = []
a('{title}')
a('=' * len(info['title']))
a('\n.. |pic{num}| image:: /images/examples/{dunder}.png'
'\n :width: 50%'
'\n :align: middle')
a('\n|pic{num}|')
a()
for paragraph in info['enhanced_description']:
for line in paragraph:
a(line)
a()
# include images
last_lang = '.py'
for fname in info['files']:
full_name = slash(info['dir'], fname)
ext = re.search(r'\.\w+$', fname).group(0)
a('\n.. _`' + full_name.replace(sep, '_') + '`:')
# double separator if building on windows (sphinx skips backslash)
if '\\' in full_name:
full_name = full_name.replace(sep, sep * 2)
if ext in ['.png', '.jpg', '.jpeg']:
title = 'Image **' + full_name + '**'
a('\n' + title)
a('~' * len(title))
a('\n.. image:: ../../../examples/' + full_name)
a(' :align: ' ' center')
else: # code
title = 'File **' + full_name + '**'
a('\n' + title)
a('~' * len(title))
if ext != last_lang and ext != '.txt':
a('\n.. highlight:: ' + ext[1:])
a(' :linenothreshold: 3')
last_lang = ext
# prevent highlight errors with 'none'
elif ext == '.txt':
a('\n.. highlight:: none')
a(' :linenothreshold: 3')
last_lang = ext
a('\n.. include:: ../../../examples/' + full_name)
a(' :code:')
return '\n'.join(output) + '\n'
def write_file(name, s):
''' write the string to the filename '''
# Make sure all the directories has been created before
# trying to write to the file
directory = os.path.dirname(name)
if not os.path.exists(directory):
os.makedirs(directory)
with open(name, 'w') as f:
f.write(s)
def make_index(infos):
''' return string of the rst for the gallery's index.rst file. '''
start_string = '''
Gallery of Examples
===================
.. toctree::
:maxdepth: 1
gallery'''
output = [start_string]
for info in infos:
output.append(' gen__{}'.format(info['dunder']))
return '\n'.join(output) + '\n'
def write_all_rst_pages():
''' Do the main task of writing the gallery,
detail, and index rst pages.
'''
infos = get_infos(screenshots_dir)
s = make_gallery_page(infos)
write_file(gallery_filename, s)
for info in infos:
s = make_detail_page(info)
detail_name = slash(generation_dir,
'gen__{}.rst'.format(info['dunder']))
write_file(detail_name, s)
s = make_index(infos)
index_name = slash(generation_dir, 'index.rst')
write_file(index_name, s)
Logger.info('gallery.py: Created gallery rst documentation pages.')
if __name__ == '__main__':
write_all_rst_pages()