update doc

jdum · Dec 23, 2023 · f5190b7 · f5190b7
1 parent 182f8b9
commit f5190b7
Show file tree

Hide file tree

Showing 4 changed files with 231 additions and 10 deletions.
diff --git a/doc/document.html b/doc/document.html
@@ -883,7 +883,32 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
                 part = document.get_part(url)
                 self.set_part(url, part)
                 media_type = document_manifest.get_media_type(url)
-                manifest.add_full_path(url, media_type)</code></pre>
+                manifest.add_full_path(url, media_type)
+
+    def add_page_break_style(self):
+        &#34;&#34;&#34;Ensure that the document contains the style required for a manual page break.
+
+        Then a manual page break can be added to the document with:
+            from paragraph import PageBreak
+            ...
+            document.body.append(PageBreak())
+
+        Note: this style uses the property &#39;fo:break-after&#39;, another
+        possibility coul be the property &#39;fo:break-before&#39;
+        &#34;&#34;&#34;
+        if existing := self.get_style(  # noqa: SIM102
+            family=&#34;paragraph&#34;,
+            name_or_element=&#34;odfdopagebreak&#34;,
+        ):
+            if properties := existing.get_properties():  # noqa: SIM102
+                if properties[&#34;fo:break-after&#34;] == &#34;page&#34;:
+                    return
+        style = (
+            &#39;&lt;style:style style:family=&#34;paragraph&#34; style:parent-style-name=&#34;Standard&#34; &#39;
+            &#39;style:name=&#34;odfdopagebreak&#34;&gt;&#39;
+            &#39;&lt;style:paragraph-properties fo:break-after=&#34;page&#34;/&gt;&lt;/style:style&gt;&#39;
+        )
+        self.insert_style(style, automatic=False)</code></pre>
 </details>
 </section>
 <section>
@@ -1648,7 +1673,32 @@ <h2 class="section-title" id="header-classes">Classes</h2>
                 part = document.get_part(url)
                 self.set_part(url, part)
                 media_type = document_manifest.get_media_type(url)
-                manifest.add_full_path(url, media_type)</code></pre>
+                manifest.add_full_path(url, media_type)
+
+    def add_page_break_style(self):
+        &#34;&#34;&#34;Ensure that the document contains the style required for a manual page break.
+
+        Then a manual page break can be added to the document with:
+            from paragraph import PageBreak
+            ...
+            document.body.append(PageBreak())
+
+        Note: this style uses the property &#39;fo:break-after&#39;, another
+        possibility coul be the property &#39;fo:break-before&#39;
+        &#34;&#34;&#34;
+        if existing := self.get_style(  # noqa: SIM102
+            family=&#34;paragraph&#34;,
+            name_or_element=&#34;odfdopagebreak&#34;,
+        ):
+            if properties := existing.get_properties():  # noqa: SIM102
+                if properties[&#34;fo:break-after&#34;] == &#34;page&#34;:
+                    return
+        style = (
+            &#39;&lt;style:style style:family=&#34;paragraph&#34; style:parent-style-name=&#34;Standard&#34; &#39;
+            &#39;style:name=&#34;odfdopagebreak&#34;&gt;&#39;
+            &#39;&lt;style:paragraph-properties fo:break-after=&#34;page&#34;/&gt;&lt;/style:style&gt;&#39;
+        )
+        self.insert_style(style, automatic=False)</code></pre>
 </details>
 <h3>Static methods</h3>
 <dl>
@@ -1803,6 +1853,47 @@ <h2 id="arguments">Arguments</h2>
     return full_path</code></pre>
 </details>
 </dd>
+<dt id="odfdo.document.Document.add_page_break_style"><code class="name flex">
+<span>def <span class="ident">add_page_break_style</span></span>(<span>self)</span>
+</code></dt>
+<dd>
+<div class="desc"><p>Ensure that the document contains the style required for a manual page break.</p>
+<p>Then a manual page break can be added to the document with:
+from paragraph import PageBreak
+&hellip;
+document.body.append(PageBreak())</p>
+<p>Note: this style uses the property 'fo:break-after', another
+possibility coul be the property 'fo:break-before'</p></div>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">def add_page_break_style(self):
+    &#34;&#34;&#34;Ensure that the document contains the style required for a manual page break.
+
+    Then a manual page break can be added to the document with:
+        from paragraph import PageBreak
+        ...
+        document.body.append(PageBreak())
+
+    Note: this style uses the property &#39;fo:break-after&#39;, another
+    possibility coul be the property &#39;fo:break-before&#39;
+    &#34;&#34;&#34;
+    if existing := self.get_style(  # noqa: SIM102
+        family=&#34;paragraph&#34;,
+        name_or_element=&#34;odfdopagebreak&#34;,
+    ):
+        if properties := existing.get_properties():  # noqa: SIM102
+            if properties[&#34;fo:break-after&#34;] == &#34;page&#34;:
+                return
+    style = (
+        &#39;&lt;style:style style:family=&#34;paragraph&#34; style:parent-style-name=&#34;Standard&#34; &#39;
+        &#39;style:name=&#34;odfdopagebreak&#34;&gt;&#39;
+        &#39;&lt;style:paragraph-properties fo:break-after=&#34;page&#34;/&gt;&lt;/style:style&gt;&#39;
+    )
+    self.insert_style(style, automatic=False)</code></pre>
+</details>
+</dd>
 <dt id="odfdo.document.Document.del_part"><code class="name flex">
 <span>def <span class="ident">del_part</span></span>(<span>self, path)</span>
 </code></dt>
@@ -2472,8 +2563,9 @@ <h1>Index</h1>
 <ul>
 <li>
 <h4><code><a title="odfdo.document.Document" href="#odfdo.document.Document">Document</a></code></h4>
-<ul class="two-column">
+<ul class="">
 <li><code><a title="odfdo.document.Document.add_file" href="#odfdo.document.Document.add_file">add_file</a></code></li>
+<li><code><a title="odfdo.document.Document.add_page_break_style" href="#odfdo.document.Document.add_page_break_style">add_page_break_style</a></code></li>
 <li><code><a title="odfdo.document.Document.body" href="#odfdo.document.Document.body">body</a></code></li>
 <li><code><a title="odfdo.document.Document.clone" href="#odfdo.document.Document.clone">clone</a></code></li>
 <li><code><a title="odfdo.document.Document.del_part" href="#odfdo.document.Document.del_part">del_part</a></code></li>

diff --git a/doc/index.html b/doc/index.html
@@ -94,6 +94,7 @@ <h1 class="title">Package <code>odfdo</code></h1>
     &#34;Note&#34;,
     &#34;PREV_SIBLING&#34;,
     &#34;Paragraph&#34;,
+    &#34;PageBreak&#34;,
     &#34;RectangleShape&#34;,
     &#34;Reference&#34;,
     &#34;ReferenceMark&#34;,
@@ -173,7 +174,7 @@ <h1 class="title">Package <code>odfdo</code></h1>
 from .manifest import Manifest
 from .meta import Meta
 from .note import Annotation, AnnotationEnd, Note
-from .paragraph import LineBreak, Paragraph, Spacer, Span, Tab
+from .paragraph import LineBreak, PageBreak, Paragraph, Spacer, Span, Tab
 from .reference import Reference, ReferenceMark, ReferenceMarkEnd, ReferenceMarkStart
 from .section import Section
 from .shapes import ConnectorShape, DrawGroup, EllipseShape, LineShape, RectangleShape
@@ -393,6 +394,26 @@ <h2 class="section-title" id="header-submodules">Sub-modules</h2>
 <section>
 <h2 class="section-title" id="header-functions">Functions</h2>
 <dl>
+<dt id="odfdo.PageBreak"><code class="name flex">
+<span>def <span class="ident">PageBreak</span></span>(<span>)</span>
+</code></dt>
+<dd>
+<div class="desc"><p>Return an empty paragraph with a manual page break.</p>
+<p>Using this function requires to register the page break style with:
+document.add_page_break_style()</p></div>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">def PageBreak():
+    &#34;&#34;&#34;Return an empty paragraph with a manual page break.
+
+    Using this function requires to register the page break style with:
+        document.add_page_break_style()
+    &#34;&#34;&#34;
+    return Paragraph(&#34;&#34;, style=&#34;odfdopagebreak&#34;)</code></pre>
+</details>
+</dd>
 <dt id="odfdo.create_table_cell_style"><code class="name flex">
 <span>def <span class="ident">create_table_cell_style</span></span>(<span>border=None, border_top=None, border_bottom=None, border_left=None, border_right=None, padding=None, padding_top=None, padding_bottom=None, padding_left=None, padding_right=None, background_color=None, shadow=None, color=None)</span>
 </code></dt>
@@ -6461,7 +6482,32 @@ <h3>Inherited members</h3>
                 part = document.get_part(url)
                 self.set_part(url, part)
                 media_type = document_manifest.get_media_type(url)
-                manifest.add_full_path(url, media_type)</code></pre>
+                manifest.add_full_path(url, media_type)
+
+    def add_page_break_style(self):
+        &#34;&#34;&#34;Ensure that the document contains the style required for a manual page break.
+
+        Then a manual page break can be added to the document with:
+            from paragraph import PageBreak
+            ...
+            document.body.append(PageBreak())
+
+        Note: this style uses the property &#39;fo:break-after&#39;, another
+        possibility coul be the property &#39;fo:break-before&#39;
+        &#34;&#34;&#34;
+        if existing := self.get_style(  # noqa: SIM102
+            family=&#34;paragraph&#34;,
+            name_or_element=&#34;odfdopagebreak&#34;,
+        ):
+            if properties := existing.get_properties():  # noqa: SIM102
+                if properties[&#34;fo:break-after&#34;] == &#34;page&#34;:
+                    return
+        style = (
+            &#39;&lt;style:style style:family=&#34;paragraph&#34; style:parent-style-name=&#34;Standard&#34; &#39;
+            &#39;style:name=&#34;odfdopagebreak&#34;&gt;&#39;
+            &#39;&lt;style:paragraph-properties fo:break-after=&#34;page&#34;/&gt;&lt;/style:style&gt;&#39;
+        )
+        self.insert_style(style, automatic=False)</code></pre>
 </details>
 <h3>Static methods</h3>
 <dl>
@@ -6616,6 +6662,47 @@ <h2 id="arguments">Arguments</h2>
     return full_path</code></pre>
 </details>
 </dd>
+<dt id="odfdo.Document.add_page_break_style"><code class="name flex">
+<span>def <span class="ident">add_page_break_style</span></span>(<span>self)</span>
+</code></dt>
+<dd>
+<div class="desc"><p>Ensure that the document contains the style required for a manual page break.</p>
+<p>Then a manual page break can be added to the document with:
+from paragraph import PageBreak
+&hellip;
+document.body.append(PageBreak())</p>
+<p>Note: this style uses the property 'fo:break-after', another
+possibility coul be the property 'fo:break-before'</p></div>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">def add_page_break_style(self):
+    &#34;&#34;&#34;Ensure that the document contains the style required for a manual page break.
+
+    Then a manual page break can be added to the document with:
+        from paragraph import PageBreak
+        ...
+        document.body.append(PageBreak())
+
+    Note: this style uses the property &#39;fo:break-after&#39;, another
+    possibility coul be the property &#39;fo:break-before&#39;
+    &#34;&#34;&#34;
+    if existing := self.get_style(  # noqa: SIM102
+        family=&#34;paragraph&#34;,
+        name_or_element=&#34;odfdopagebreak&#34;,
+    ):
+        if properties := existing.get_properties():  # noqa: SIM102
+            if properties[&#34;fo:break-after&#34;] == &#34;page&#34;:
+                return
+    style = (
+        &#39;&lt;style:style style:family=&#34;paragraph&#34; style:parent-style-name=&#34;Standard&#34; &#39;
+        &#39;style:name=&#34;odfdopagebreak&#34;&gt;&#39;
+        &#39;&lt;style:paragraph-properties fo:break-after=&#34;page&#34;/&gt;&lt;/style:style&gt;&#39;
+    )
+    self.insert_style(style, automatic=False)</code></pre>
+</details>
+</dd>
 <dt id="odfdo.Document.del_part"><code class="name flex">
 <span>def <span class="ident">del_part</span></span>(<span>self, path)</span>
 </code></dt>
@@ -27057,7 +27144,8 @@ <h2 id="arguments">Arguments</h2>
         # FIXME cyclic import
         for item in text_or_element:
             if isinstance(item, str):
-                paragraph = Paragraph(item, style=style)
+                paragraph = Element.from_tag(&#34;text:p&#34;)
+                paragraph.style = style
                 header_or_footer.append(paragraph)
             elif isinstance(item, Element):
                 header_or_footer.append(item)
@@ -41484,6 +41572,7 @@ <h1>Index</h1>
 </li>
 <li><h3><a href="#header-functions">Functions</a></h3>
 <ul class="">
+<li><code><a title="odfdo.PageBreak" href="#odfdo.PageBreak">PageBreak</a></code></li>
 <li><code><a title="odfdo.create_table_cell_style" href="#odfdo.create_table_cell_style">create_table_cell_style</a></code></li>
 <li><code><a title="odfdo.default_boolean_style" href="#odfdo.default_boolean_style">default_boolean_style</a></code></li>
 <li><code><a title="odfdo.default_currency_style" href="#odfdo.default_currency_style">default_currency_style</a></code></li>
@@ -41644,8 +41733,9 @@ <h4><code><a title="odfdo.Content" href="#odfdo.Content">Content</a></code></h4>
 </li>
 <li>
 <h4><code><a title="odfdo.Document" href="#odfdo.Document">Document</a></code></h4>
-<ul class="two-column">
+<ul class="">
 <li><code><a title="odfdo.Document.add_file" href="#odfdo.Document.add_file">add_file</a></code></li>
+<li><code><a title="odfdo.Document.add_page_break_style" href="#odfdo.Document.add_page_break_style">add_page_break_style</a></code></li>
 <li><code><a title="odfdo.Document.body" href="#odfdo.Document.body">body</a></code></li>
 <li><code><a title="odfdo.Document.clone" href="#odfdo.Document.clone">clone</a></code></li>
 <li><code><a title="odfdo.Document.del_part" href="#odfdo.Document.del_part">del_part</a></code></li>

diff --git a/doc/paragraph.html b/doc/paragraph.html
@@ -64,6 +64,7 @@ <h1 class="title">Module <code>odfdo.paragraph</code></h1>
 
 __all__ = [
     &#34;LineBreak&#34;,
+    &#34;PageBreak&#34;,
     &#34;Paragraph&#34;,
     &#34;Spacer&#34;,
     &#34;Span&#34;,
@@ -790,6 +791,15 @@ <h1 class="title">Module <code>odfdo.paragraph</code></h1>
                 self.style = style
 
 
+def PageBreak():
+    &#34;&#34;&#34;Return an empty paragraph with a manual page break.
+
+    Using this function requires to register the page break style with:
+        document.add_page_break_style()
+    &#34;&#34;&#34;
+    return Paragraph(&#34;&#34;, style=&#34;odfdopagebreak&#34;)
+
+
 Span._define_attribut_property()
 
 register_element_class(Span)
@@ -801,6 +811,29 @@ <h1 class="title">Module <code>odfdo.paragraph</code></h1>
 <section>
 </section>
 <section>
+<h2 class="section-title" id="header-functions">Functions</h2>
+<dl>
+<dt id="odfdo.paragraph.PageBreak"><code class="name flex">
+<span>def <span class="ident">PageBreak</span></span>(<span>)</span>
+</code></dt>
+<dd>
+<div class="desc"><p>Return an empty paragraph with a manual page break.</p>
+<p>Using this function requires to register the page break style with:
+document.add_page_break_style()</p></div>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">def PageBreak():
+    &#34;&#34;&#34;Return an empty paragraph with a manual page break.
+
+    Using this function requires to register the page break style with:
+        document.add_page_break_style()
+    &#34;&#34;&#34;
+    return Paragraph(&#34;&#34;, style=&#34;odfdopagebreak&#34;)</code></pre>
+</details>
+</dd>
+</dl>
 </section>
 <section>
 <h2 class="section-title" id="header-classes">Classes</h2>
@@ -3117,6 +3150,11 @@ <h1>Index</h1>
 <li><code><a title="odfdo" href="index.html">odfdo</a></code></li>
 </ul>
 </li>
+<li><h3><a href="#header-functions">Functions</a></h3>
+<ul class="">
+<li><code><a title="odfdo.paragraph.PageBreak" href="#odfdo.paragraph.PageBreak">PageBreak</a></code></li>
+</ul>
+</li>
 <li><h3><a href="#header-classes">Classes</a></h3>
 <ul>
 <li>

diff --git a/doc/style.html b/doc/style.html
@@ -53,7 +53,6 @@ <h1 class="title">Module <code>odfdo.style</code></h1>
 from .datatype import Boolean
 from .element import Element, register_element_class
 from .image import DrawImage
-from .paragraph import Paragraph
 from .utils import (
     FALSE_FAMILY_MAP_REVERSE,
     FAMILY_MAPPING,
@@ -894,7 +893,8 @@ <h1 class="title">Module <code>odfdo.style</code></h1>
         # FIXME cyclic import
         for item in text_or_element:
             if isinstance(item, str):
-                paragraph = Paragraph(item, style=style)
+                paragraph = Element.from_tag(&#34;text:p&#34;)
+                paragraph.style = style
                 header_or_footer.append(paragraph)
             elif isinstance(item, Element):
                 header_or_footer.append(item)
@@ -2514,7 +2514,8 @@ <h2 id="arguments">Arguments</h2>
         # FIXME cyclic import
         for item in text_or_element:
             if isinstance(item, str):
-                paragraph = Paragraph(item, style=style)
+                paragraph = Element.from_tag(&#34;text:p&#34;)
+                paragraph.style = style
                 header_or_footer.append(paragraph)
             elif isinstance(item, Element):
                 header_or_footer.append(item)