{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Detailed Usage Instructions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "Given here is a brief overview. See the ipython notebooks within the `examples` folder within this repository for more detailed usage examples. \n", "\n", "### `Doc` the Document builder\n", "\n", "The `Doc` class from `pydocmaker` is the basic building element for making a report. Here each element will be appended to the end of the document if no `index` or `chapter` is given. Alternatively the chapter to which to append a document part can be specified by `chapter='xxx'`. Furthermore you can also specify the index position (after which part of the document to insert) by adding `index=i` where `i` is `int`. You can use the object like a list.\n", "\n", "\n", "\n", "### Document part schemas\n", "\n", "The basic building blocks for a document are called `document parts` and are always either of type `dict` or type `str` (A string will automatically parsed as a text dict element). \n", "\n", "Each document part has a `typ` field which states the type of document part and a `children` field, which can be either `string` or `list`. This way hirachical documents can be build if needed. \n", "\n", "The `document-parts` are:\n", "- `text`: holds text as string (`children`) which will inserted directly as raw text\n", "- `markdown`: holds text as string (`children`) which will be rendered by markdown markup language before parsing into the documents\n", "- `image`: holds all needed information to render an image in a report. The image data is saved as a string in base64 encoded format in the `imageblob` field. A `caption` (str) can be given which will be inserted below the image. The filename is given by the `children` field. The relative width can be given by the `width` field (float). \n", "- `verbatim`: holds text as string (`children`) which will be inserted as preformatted text into the documents\n", "- `iter`: a meta `document-part` which holds n sub `document-parts` in the `children` field which will be rendered and inserted into the documents in given order. \n", "\n", "An example of the whole schema is given below.\n", "\n", "```json\n", "{\n", " \"text\": {\"typ\": \"text\", \"children\": \"\"},\n", " \"markdown\": {\"typ\": \"markdown\", \"children\": \"\"},\n", " \"image\": {\"typ\": \"image\", \"children\": \"\", \"imageblob\": \"\", \"caption\": \"\", \"width\": 0.8},\n", " \"verbatim\": {\"typ\": \"verbatim\", \"children\": \"\"},\n", " \"iter\": {\"typ\": \"iter\", \"children\": [] }\n", "}\n", "```\n", "\n", "\n", "### Adding document parts to a doc\n", "\n", "Alternatively you can add elements to a document directly using the add and add_kw methods of the document builders:\n" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "import pydocmaker as pyd" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", " \n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
dummy text
\n", "\n", "

some dummy markdown text!

\n", "\n", "
\n", "\n", "
this text will be shown preformatted!
\n", "\n", "
\n", "\n", "
Figure 1: GitHub-Mark-ea2971cee799.png
\n", "\n", "\n", "\n", "\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "\n", "doc = pyd.Doc()\n", "doc.add('dummy text')\n", "doc.add({\"typ\": \"markdown\",\"children\": \"some dummy markdown text!\"})\n", "doc.add_kw('verbatim', 'this text will be shown preformatted!')\n", "doc.add_image('https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png', caption='', children='')\n", "\n", "doc.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Working with images\n", "\n", "Image from pyplot figure\n" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", " \n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
\n", "\n", "
Figure 1: test figure
\n", "\n", "\n", "\n", "\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import matplotlib.pyplot as plt\n", "\n", "fig = plt.figure()\n", "plt.plot([1, 2, 3], [5, 6, 4])\n", "\n", "doc = pyd.Doc()\n", "doc.add(pyd.constr.image_from_fig(caption='test figure', fig=fig))\n", "plt.close()\n", "doc.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Image from numpy array " ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "pydocmaker.Doc with N=0 chapters, K=1 elements." ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import numpy as np\n", "m = np.array([np.arange(255).astype(np.uint8).tolist() for i in range(255)], dtype=np.uint8)\n", "doc = pyd.Doc()\n", "doc.add(pyd.constr.image_from_obj(m, caption = 'numpy generated image', width=0.8))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "### Adding parts to specific chapters\n", "\n", "as said above you can also add elements to specific chapters or locations. below is an example\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", " \n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "

Introduction

\n", "\n", "

This text will be appended to the first section after the 2nd element (index is zero based!), which is the text (the chapter definition itself is the 1st element!)

\n", "\n", "
dummy text which will be added to the introduction
\n", "\n", "

Second Chapter

\n", "\n", "

This is my fancy markdown text for the Second Chapter

\n", "\n", "
\n", "\n", "
Figure 1: GitHub-Mark-ea2971cee799.png
\n", "\n", "\n", "\n", "\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "doc = pyd.Doc()\n", "\n", "# this will add a section 'Introduction'\n", "doc.add_chapter('Introduction')\n", "\n", "# now I can add / access the section (which is a Doc) direcly like a dict\n", "doc.add('dummy text which will be added to the introduction', chapter='Introduction')\n", "\n", "# this will add the section 'Weather Info' and add a markdown element to it\n", "doc.add_kw('markdown', 'This is my fancy `markdown` text for the Second Chapter', \n", " chapter='Second Chapter')\n", "\n", "# I can also add parts to the Introduction like this\n", "doc.add_kw('markdown', 'This text will be appended to the first section after the 2nd element (`index` is zero based!), which is the text (the chapter definition itself is the 1st element!)', \n", " index=1)\n", "\n", "# and like this\n", "doc.add_image(\"https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png\", \n", " chapter='Second Chapter')\n", "\n", "\n", "doc.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Using the low level ``constr`` constructor factory\n", "\n", "`document-parts` are under the hood constructed using the `constr` class which is basically a factory for `document-parts`" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", " \n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "

My Markdown text

\n", "\n", "
My plain text
\n", "\n", "
\n", "\n", "
My preformatted text
\n", "\n", "
\n", "\n", "
Figure 1: Empty image
\n", "\n", "
\n", "\n", "
Figure 2: Github image
\n", "\n", "
\n", "\n", "
Figure 3: Some fancy logo
\n", "\n", "
\n", "\n", "
Figure 4: Pyplot figure
\n", "\n", "
\n", "\n", "\n", "\n", "\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "doc = pyd.Doc()\n", "\n", "docpart = pyd.constr.markdown(children='My Markdown text')\n", "doc.add(docpart)\n", "docpart = pyd.constr.text(children='My plain text')\n", "doc.add(docpart)\n", "docpart = pyd.constr.verbatim(children='My preformatted text')\n", "doc.add(docpart)\n", "docpart = pyd.constr.image(imageblob='', caption='Empty image', children='', width=0.8)\n", "doc.add(docpart)\n", "docpart = pyd.constr.image_from_link(url='https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png', caption='Github image', children='', width=0.8)\n", "doc.add(docpart)\n", "docpart = pyd.constr.image_from_file(path=r'C:\\Users\\tglaubach\\repos\\pydocmaker\\example_templates\\fancy_template.assets\\fancy_logo.png', children='Some fancy logo', caption='', width=0.8)\n", "doc.add(docpart)\n", "fig = plt.figure()\n", "plt.plot([1, 2, 3], [5, 6, 4])\n", "docpart = pyd.constr.image_from_fig(caption='Pyplot figure', width=0.8, fig=fig)\n", "doc.add(docpart)\n", "docpart = pyd.constr.image_from_obj(np.atleast_2d(np.array(np.arange(255).tolist() * 255, dtype=\"uint8\")), caption = '', width=0.8)\n", "doc.add(docpart)\n", "\n", "plt.close()\n", "doc.show()" ] } ], "metadata": { "kernelspec": { "display_name": "base", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.7" } }, "nbformat": 4, "nbformat_minor": 2 }