U Peq+@sdZddlZddlZddlmZddlmZddlmZmZddl Z ddl m Z ddl Z eeee j ZeedZeedZeed Zd Zeed Zd d ZddZddZd"ddZddZddZddZddZddZdd Zed!kredS)#a0 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 N)sep)join)dirnameabspath)LoggerZexampleszdoc/sources/images/exampleszdoc/sources/examplesz../images/examples/z gallery.rstc cstd}t|D]}|dD]}|dr ||}|dkrRdd|iVq |ddt }|d||d |d t ||d d |d d Vq qdS) a 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' z^((.+)__(.+)__([^-]+))\.png.pngNerrorz1png filename not following screenshot pattern: {}__.)dunderdirfileextsource) recompileoswalkendswithmatchformatgroupreplacerslash)dir_namepatterntfilenamemdr$6/tmp/pip-unpacked-wheel-xzebddm3/kivy/tools/gallery.pyiter_filename_info&s     r&cCsvd}d|}t||tj}|rj|ddd}|d|dd}|d |d |d|d Sd d iSdS)av parse docstring from text (normal string with ' '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. z"""|'''z!({})\s+([^\n]+)\s+\=+\s+(.*?)(\1)r   Nrr rr)Z docstringtitle descriptionfirst_sentencer z1Did not find docstring with title at top of file.)rrsearchSrrfind)textqpr"commentr+r$r$r%parse_docstring_infoDs  r3c cst|D]}d|kr$t|dqtt|d|dd|d}tj|s^td|qt|L}| }t |}d|krt|dd|W5QRqn | |W5QRX|VqdS) z 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. r rrrrz;Screen shot references source code that does not exist: %sz File: N) r&rr r examples_dirrpathexistsopenreadr3update)r file_inforfr/Zdocstring_infor$r$r%iter_docstring_infoYs(    r<Ocs|dd}dd|D}d|}|dd|dg|d <d }t||D]}||d krP|d |qPd |d td dd }tdd|}|d|}dd|dD}fdd|D}||d<d S)aF 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']. r*z cSsg|]}|ddqS)r' $newline$r).0 paragraphr$r$r% sz,enhance_info_description..r'rrrfilesz$[tT]he (?:file|image) ([\w\/]+\.\w+)_rNz&([tT]he (?:file|image) )([\w\/]+\.\w+)z\1:ref:`\2 <$folder$\2>`z$folder$cSsg|]}|ddqS)r>r'r?r@liner$r$r%rBscs(g|] }|dst|n|gqS)r() startswithtextwrapwraprF line_lengthr$r%rBsenhanced_description)splitrrfindallappendrsubr)inforLZ paragraphslinesr/regexnamefolderr$rKr%enhance_info_descriptionss*     rWcCsHddt|D}|jdddt|D]\}}||d<t|q*|S)z 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'. cSsg|]}|qSr$r$)r@ir$r$r%rBszget_infos..cSs|dS)Nrr$)xr$r$r%zget_infos..)keynum)r<sort enumeraterW)rinfosr]rRr$r$r% get_infoss  racCs4d}|g}|D]}|djf|qd|dS)zy return string of the rst (Restructured Text) of the gallery page, showing information on all screenshots found. a 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! z **{title}** (:doc:`{source}`) {description} .. image:: ../images/examples/{dunder}.png :width: 216pt :align: left :target: gen__{dunder}.htmlr'rPrr)r`Z gallery_topoutputrRr$r$r%make_gallery_pagesrdc sd$fdd }g|d|dtd|d|d|d D]}|D] }||qV|qNd }d D],}td |}td |d}|d|tddd|kr|ttd}|dkrd|d}|d||dt||d||dqxd|d}|d||dt|||krt|dkrt|d|dd|d |}n|dkr|d!|d |}|d"||d#qxddS)%zE return str of the rst text for the detail page of the file in info. cs|jfdS)z? append formatted s to output, which will be joined into lines N)rPr)srRrcr$r%aszmake_detail_page..az{title}=r)zU .. |pic{num}| image:: /images/examples/{dunder}.png :width: 50% :align: middlez |pic{num}|rMz.pyrCrz\.\w+$rz .. _`rDz`:\r)rz.jpgz.jpegzImage **z**r'~z .. image:: ../../../examples/z :align: centerzFile **z.txtz .. highlight:: r Nz :linenothreshold: 3z .. highlight:: nonez .. include:: ../../../examples/z :code:)re)lenrrr,rrrr) rRrhrArGZ last_langfnameZ full_namerr)r$rgr%make_detail_pagesL            rnc CsFtj|}tj|s"t|t|d}||W5QRXdS)z" write the string to the filename wN)rr5rr6makedirsr7write)rUrf directoryr;r$r$r% write_files     rscCs6d}|g}|D]}|d|dqd|dS)z< return string of the rst for the gallery's index.rst file. zT Gallery of Examples =================== .. toctree:: :maxdepth: 1 galleryz gen__{}rr'rb)r`Z start_stringrcrRr$r$r% make_indexs rtcCsttt}t|}tt||D]*}t|}ttd|d}t||qt |}ttd}t||t ddS)zO Do the main task of writing the gallery, detail, and index rst pages. z gen__{}.rstrz index.rstz4gallery.py: Created gallery rst documentation pages.N) rascreenshots_dirrdrsgallery_filenamernrgeneration_dirrrtrrR)r`rfrRZ detail_nameZ index_namer$r$r%write_all_rst_pages.s     rx__main__)r=)__doc__rros.pathrrrrrZkivyZ kivy.loggerrrI__file__base_dirr4rurwZ image_dirrvr&r3r<rWrardrnrsrtrx__name__r$r$r$r%s4         --6