Merge pull request #110 from COMP1010UNSW/maddy-render-options

Implement rendering options

Author: MaddyGuthridge

.github/workflows/mkdocs-dryrun.yml

@@ -24,7 +24,7 @@ jobs:
         id: python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.10'
 
       # Install dependencies using Poetry
       - uses: Gr1N/setup-poetry@v9

.github/workflows/mkdocs.yml

@@ -36,7 +36,7 @@ jobs:
         id: python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.10'
 
       # Install dependencies using Poetry
       - uses: Gr1N/setup-poetry@v9

.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: '3.10'
 
       # Install dependencies using Poetry
       - uses: Gr1N/setup-poetry@v9

.github/workflows/python-app.yml

@@ -26,10 +26,10 @@ jobs:
     - uses: actions/checkout@v4
       with:
         submodules: 'recursive'
-    - name: Set up Python 3.9
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
     - uses: Gr1N/setup-poetry@v9
     - uses: actions/cache@v4
       with:
@@ -60,10 +60,10 @@ jobs:
     - uses: actions/checkout@v4
       with:
         submodules: 'recursive'
-    - name: Set up Python 3.9
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
     - uses: Gr1N/setup-poetry@v9
     - uses: actions/cache@v4
       with:
@@ -81,10 +81,10 @@ jobs:
     - uses: actions/checkout@v4
       with:
         submodules: 'recursive'
-    - name: Set up Python 3.9
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
     - uses: Gr1N/setup-poetry@v9
     - uses: actions/cache@v4
       with:

README.md

@@ -46,9 +46,7 @@ Learn more by reading [the documentation](https://comp1010unsw.github.io/pyhtml-
     <h1>
       Hello, world!
     </h1>
-    <p>
-      This is my amazing website!
-    </p>
+    <p>This is my amazing website!</p>
   </body>
 </html>
 

docs/api.md

@@ -9,9 +9,10 @@
         - attributes
         - "_get_tag_name"
         - "_get_default_attributes"
+        - "_get_default_render_options"
         - "_get_tag_pre_content"
-        - "_render"
         - "_escape_children"
+        - "_render"
 
 ::: pyhtml.SelfClosingTag
     options:
@@ -20,3 +21,10 @@
 ::: pyhtml.WhitespaceSensitiveTag
     options:
       members:
+
+::: pyhtml.RenderOptions
+    options:
+      members:
+        - indent
+        - spacing
+        - union

docs/compatibility.md

@@ -29,16 +29,29 @@ modify the original instance, as I found the old behaviour confusing and
 bug-prone.
 
 ```py
->>> para = p.p("Base paragraph")
->>> para2 = para("Extra text")
->>> para2
-<p>
+>>> span1 = p.span("Base paragraph")
+>>> span2 = span1("Extra text")
+>>> span2
+<span>
   Base paragraph
   Extra text
-</p>
->>> para
-<p>
+</span>
+>>> span1
+<span>
   Base paragraph
-</p>
+</span>
+
+```
+
+## Spacing between tag instances
+
+Certain tags have default spacing, which helps to avoid subtle rendering
+annoyances such as unwanted spaces between linked text and punctuation in
+paragraphs.
+
+```py
+>>> print(str(p.p(p.a(href="https://example.com")("Example website"), "!")))
+<p><a href="https://example.com">Example website</a>!</p>
+>>> # Notice how there is no spacing between the link and the exclamation point
 
 ```

docs/index.md

@@ -32,9 +32,7 @@ Build HTML documents in Python with a simple and learnable syntax.
     <h1>
       Hello, world!
     </h1>
-    <p>
-      This is my amazing website!
-    </p>
+    <p>This is my amazing website!</p>
   </body>
 </html>
 

docs/learn/advanced.md

@@ -58,7 +58,29 @@ for person in staff_members:
     ))
 ```
 
-### HTML comments
+## Rendering options
+
+If you need more control over how PyHTML renders your output HTML, you can use
+the [`p.RenderOptions`][pyhtml.RenderOptions] class to specify these.
+
+For example, if you don't want any whitespace between your HTML components,
+you can use `p.RenderOptions(spacing="")` to remove it.
+
+```py
+>>> import pyhtml as p
+>>> print(str(p.div(p.RenderOptions(spacing=""))(
+... p.i("No"),
+... p.b("spaces"),
+... p.u("here!")
+... )))
+<div><i>No</i><b>spaces</b><u>here!</u></div>
+
+```
+
+For more information about the specific allowed properties, view
+[this documentation][pyhtml.RenderOptions].
+
+## HTML comments
 
 You can add comments to HTML by using the `Comment` tag. These will be included
 in the output HTML, which can be useful for debugging your server from your web
@@ -77,8 +99,8 @@ browser.
 ## Embedding raw HTML
 
 By default, PyHTML [escapes certain characters](https://www.w3schools.com/html/html_entities.asp)
-within strings passed to tags. This is done to avoid user content from taking
-control of your resultant webpages in what is called a
+within strings passed to tags. This is done to prevent user content from taking
+control of your webpages in what is called a
 [cross-site scripting (XSS) attack](https://owasp.org/www-community/attacks/xss/).
 
 Sometimes, you may wish to embed an existing HTML string inside of PyHTML. You
@@ -94,13 +116,13 @@ can do this using the `p.DangerousRawHtml` tag.
 
 ***Be careful though!*** PyHTML escapes these sequences for good reason, so
 don't use `DangerousRawHtml` unless you have a *very good reason*, and are
-certain that your text is trusted.
+certain that the text you are passing it is trusted.
 
 ## Custom tags
 
 Since this library includes all modern HTML tags, it is very unlikely that
 you'll need to do create a custom tag. However if you really need to, you can
-use the `create_tag` function
+use the `create_tag` function.
 
 ```py
 >>> import pyhtml as p

docs/stylesheets/extra.css

@@ -5,6 +5,11 @@
     --md-primary-fg-color: #ffdf77 !important;
 }
 
+/* Fix spacing around nested nav items */
+.md-nav__item--nested {
+    padding-bottom: 8px !important;
+}
+
 .md-header {
     /* Text colour on header */
     color: #000000 !important;