-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathDocumentation.html
396 lines (355 loc) · 22.1 KB
/
Documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8"/>
<head>
<meta name="description" content="Sierra - A Python micro templating engine for web frameworks">
<meta name="keywords" content="html, css, js, jinja, django, python, web framework, templating">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation | Sierra - 2.4.0</title>
<link rel="apple-touch-icon" href="./img/sierra.png">
<link href="./css/style.css" rel="stylesheet">
<link href="./css/prism.css" rel="stylesheet">
<script src="./js/prism.js"></script>
</head>
<body>
<a href="https://github.com/BrainStormYourWayIn/sierra"><img src="./img/sierra.png" height="137" width="362" alt="Sierra logo"/></a>
<h1>Documentation - Sierra v2.4.0</h1>
<div id="first_up">
<p>
Wecome to the documentation of Sierra - <b>Sierra is a Python library to write HTML and CSS in pure Python using the DOM API in a simple yet elegant manner.</b>
Take advantage of Python's powerful functionalities with ease. <b>Loops, variables, functions, libraries</b> - you name it, you have it.
You can now develop your web application purely in Python, taking full advantage of its powerful functionalities with <b>simple and elegant syntax.</b>
You can use this along with another <b>templating engine</b>, or use it <b>standalone</b> - even without a web framework, if you like.
If you have any specific requests, open a discussion/issue on our GitHub page . Any contributions can also be made there.
</p>
<p id="license">Please read our <a href="https://github.com/BrainStormYourWayIn/sierra/blob/main/LICENSE">LICENSE</a> before moving forward.</p>
</div>
<p>Contents:</p>
<ul id="pagelinks">
<li><a href="#tags" rel="noopener noreferrer">Opening tags, Creating custom functions for you own, and controlling their behavior</a></li>
<li><a href="#css-ing" rel="noopener noreferrer">Using CSS</a></li>
<li><a href="#tTags" rel="noopener noreferrer">Working with div, section and p tags</a></li>
<li><a href="#add_img" rel="noopener noreferrer">Adding images</a></li>
<li><a href="#tables" rel="noopener noreferrer">Working with tables (Pandas supported)</a></li>
<li><a href="#bullets_and_lists" rel="noopener noreferrer">Bulleted lists (ordered and unordered)</a></li>
<li><a href="#des_lists" rel="noopener noreferrer">Adding a description list</a></li>
<li><a href="#other_funcs" rel="noopener noreferrer">Other functions (add Bootstrap, script, escaping and more)</a></li>
<li><a href="py_out.html" target='_blank' rel="noopener noreferrer">Working with Python Loops, Functions, Variables, Conditions and others</a></li>
</ul>
<p>Let's get started</p>
<div id="starting_off">
<pre class="command-line language-powershell" data-prompt="$"><code>pip3 install sierra</code></pre>
<p>
can be done as an easier way of installing. You can also clone the repository and work inside of src/sierra if you like.
<br>
To import the library, simply use:
</p>
<pre class="language-python"><code>from sierra import *</code></pre>
<p>Once imported, <b>the first line of syntax is mandatory</b>, and all development to be displayed on the webpage must come after this:</p>
<pre class="line-numbers"><code class="language-py">title(Title, icon=False)
#Args:
# Title(str, compulsory) : Title of the HTML file.
# icon(str, optional) : Icon to be displayed. Should be a .ico file. Defaults to no icon.</code></pre>
<p>
This creates an <code>index.html</code> and a <code>style.css</code> in the working directory.
<br>
You can add a header with <code class="language-py">head()</code>. Start the body of the web application with <code class="language-py">openBody()</code>. Add CSS with <code class="language-py">**kwargs</code>.
</p>
<pre class="line-numbers"><code class="language-py">head(Head, type='header', **kwargs)
# head('Sierra', type='h1', color='#4287f5', font_family='Times New Roman')
#Args:
# Head (str, compulsory) : Caption header.
# type (str, optional) : Header type. Anything from 'h1' to 'h6'
# **kwargs (optional) : CSS styling arguments
openBody(**kwargs)
# openBody(background_color='blue', opacity=1.8)</code></pre>
<p>
You may notice in styling with <code class="language-py">**kwargs</code>, that the styling argument <code>font-family</code> and <code>background-color</code> is entered in as <code>font_family</code> and <code>background-color</code>.
That is, underscores are used in <code class="language-py">**kwargs</code> in the place of hyphens.
This is because Python returns a <code class="language-py">SyntaxError</code> when hyphens are used in the key of <code class="language-py">**kwargs</code>.
<br>
Hence, use underscores in <code class="language-py">**kwargs</code> for hyphens in styling arguments.
</p>
<br>
<p>Fonts can be added with <code class="language-py">addFont()</code> which takes only one argument, which is the link to the font.</p>
<pre class="line-numbers"><code class="language-py">addFont(font_link)
# If you're using Google Fonts, take only the href attribute.
# If <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@100&display=swap" rel="stylesheet">
# is the the font tag to Roboto, take only the href attribute, then use.
# addFont("https://fonts.googleapis.com/css2?family=Roboto:wght@100&display=swap")
# You can then add "'Roboto', sans-serif" to the CSS as the font_family argument/font-family attribute,
# depending on the method of CSS used (See 'Using CSS').</code></pre>
</div>
<hr>
<!--Tags-->
<div id="tags">
<pg_title>Using tags</pg_title>
<p>
Tags can be opened with <code class="language-py">Tag(name_of_tag, **kwargs)</code>, and CSS can be added with <code>.css()</code>, which is the same mechanism that <code class="language-py">head()</code> and <code class="language-py">openBody()</code> contains, except that it is now used as a function under a class.
Any inline within that tag can be entered with a context manager approach under <code class="language-py">with</code>
</p>
<pre class="line-numbers"><code class="language-py">with open_tag('tag_name', attr=None) as t:
t.css(font_color='rgb(11, 176, 89)')
# --- Any content --- </code></pre>
<p>
Coming out of <code class="language-py">with</code> automatically closes the tag. The <code class="language-py">**kwargs</code> method, in <code class="language-py">Tag()</code> enables the user to add attributes to their HTML tag.
</p>
<pre class="line-numbers"><code class="language-py">with open_tag('tag_name', attr="class='someClass' id='some_id'") as t:
t.css(font_color='rgb(11, 176, 89)')
# --- Any content --- </code></pre>
<p>
This is the equivalent of <code class="language-html"><tag_name class='someClass' id='some_id'></code>.
<br>
<b>Prefix Python-conflicting arguments with a double underscore, and use a single underscore in the place of a hyphen</b>.
Here, CSS is added to <code>tag_name</code>
<br>
With v2.4.0, you can <b>CREATE</b> functions for any tag and even control their behavior! Here's how you create 'short' tags that mostly come under <code class="language-html"><head></code>:
</p>
<pre class="line-numbers"><code class="language-py">@tag
def meta(**kwargs):
pass
meta(name="description", content="This is some description")
meta(name="viewport", content="width=device-width", initial_scale=1.0)</code></pre>
<p>This is equivalent to:</p>
<pre class="line-numbers"><code class="language-html"><meta name="description" content="This is some description">
<meta name="viewport" content="width=device-width" initial-scale=1.0></code></pre>
<p><b>Using argument <code>text=""</code> makes the tag close after the opening of the tag</b>, causing it to behave differently than tags like meta, which don't need
a closing. Remember that <code>__</code> is the equivalent of a single underscore and <code>_<code>
is the equivalent of a hyphen!</p>
<pre class="line-numbers"><code class="language-py">@tag
def script(**kwargs):
pass
script(__async="", src="some_src", text="")
# You can get any text to appear within the tag.
# Not using 'text' creates a tag similar to the <meta> tag
# This is the equivalent of <script _async= src=some-src></script></code></pre>
</div>
<hr>
<!--CSS ing-->
<div id="css-ing">
<pg_title>Using CSS</pg_title>
<p>
There are three ways you can add CSS to tags. The first one is with <code>.css()</code>, which takes in <code class="language-py">**kwargs</code>, and can only be used within the context managers of already existing syntax, like <code class="language-py">Tag()</code> and <code class="language-py">div()</code>.
Underscores are used in the key or <code class="language-py">**kwargs</code> instead of hyphens in styling attributes.
</p>
<pre class="line-numbers"><code class="language-py">.css(**kwargs)</code></pre>
<p>
The second way is to use <code class="language-py">writeCSS()</code>. It takes in a dictionary of CSS attributes, and adds them to the tag mentioned as the first argument in <code class="language-py">writeCSS().</code>.
</p>
<pre class="line-numbers"><code class="language-py">writeCSS(tag, *args)
# *args takes in a dictionary of styling attributes.
#writeCSS('pre', {"background-color": "#edf7f7", "margin-left": "0.1%"})
# This adds the specified CSS attributes in the dictionary to the tag <pre></code></pre>
<p>The third way is to use <code class="language-py">writeCSS_raw()</code>. Any text you specify in <code class="language-py">writeCSS_raw()</code> gets written into the CSS file.</p>
<pre class="line-numbers"><code class="language-py">writeCSS_raw(r"""
pre {
background-color: #edf7f7;
margin-left: 0.1%;
}""")
# This writes the exact text in writeCSS_raw() to style.css</code></pre>
</div>
<hr>
<!--tTags-->
<div id="tTags">
<pg_title>Working with div, section and p tags</pg_title>
<p>
Division and section tags can be opened the same way as <code class="language-py">Tag()</code>, except the syntax is <code class="language-py">div(**kwargs)</code> and <code class="language-py">section(**kwargs)</code> respectively.
It can take in tag attributes through the <code class="language-py">**kwargs</code> method.
Prefix conflicting arguments with a double underscore and use a single underscore for hyphens.
While adding CSS for this is similar to the mechanism in <code class="language-py">Tag()</code>, it differs in the fact that the <cpde>.css()</cpde> here prioritizes tag attributes given.
The first priority being for <code>__class</code>, the second being for <code>id</code>, and if both don't exist, CSS is just added to the tag raw.
That is <code>div</code> or <code>section</code>. Entering in both <code>__class</code> and <code>id</code> results in CSS being added to the class, and enters it to id in the absence of <code>__class</code>.
If you don't want to add CSS this way using <code>.css()</code>, use <code class="language-py">writeCSS()</code> instead, where you can add CSS to any tag/attribute, simply use <code class="language-py">'#name_of_id'</code> or <code class="language-py">'.name_of_class'</code> as the first argument.
</p>
<pre class="line-numbers"><code class="language-py">div(**kwargs)
section(**kwargs)
#with div(__class='div_class') as d:
# d.css(background_color="#e0e330")
# with section(id='sec_id'):
# p("This is a paragraph inside a section which has attribute id=sec_id, and is inside a div")
#writeCSS('#sec_id', margin_top='30px')</code></pre>
<p>
<code class="language-html"><p></code> tags can be added with <code class="language-py">p()</code>.
The text to be added goes into the <code class="language-py">text</code> attribute, and tag attributes, as usual, can be added to <code class="language-py">attr</code>.
However, <code class="language-py">p()</code> is not a context manager-based approach, as shown above under the section tag, and closes upon argument exit.
Use <code class="language-py">writeCSS()</code> or <code class="language-py">writeCSS_raw()</code> to add css.
</p>
<pre class="line-numbers"><code class="language-py">p(text, **kwargs)
# p('This is some text that goes inside a paragraph. Atrributes can be added to attr', __class='someClass')</code></pre>
</div>
<hr>
<!--Add Images-->
<div id=add_img>
<pg_title>Adding images</pg_title>
<p>
Images can be added with <code class="language-py">image()</code> as context manager based approach, <code class="language-py">.show()</code> which takes no arguments is used to display the image and <code class="language-py">.css()</code> can be used to add CSS (no priorities, just adds to <code>img</code>), or one of the other three methods to add it to a class or an id.
</p>
<pre class="line-numbers"><code class="language-py">image(src:str, **kwargs)
with image('sierra.jpg', alt='Sierra', href='https://www.google.com', target='_blank') as i:
i.show()
i.css(opacity=1.1, width='50px')</code></pre>
</div>
<hr>
<!--Add Tables-->
<div id="tables">
<pg_title>Working with tables (Pandas supported)</pg_title>
<p>
Adding a table could never have been easier with a context manager approach on <code class="language-py">Table()</code>, which takes no arguments and has objects <code class="language-py">create_table()</code> and <code class="language-py">get_table()</code>.
Sierra is compatible with Pandas, meaning just enter the path to the CSV file in <code class="language-py">arg dataframe</code> in <code class="language-py">getTable()</code>, and the table will display!
</p>
<pre class="line-numbers"><code class="language-py">get_table(self, dataframe:str, **kwargs)
with Table() as t:
t.get_table("path/to/file.csv", id="some_id")
st.css(font_family='Times New Roman')
# CSS styling arguments for get_table() and start_table() are as usual.
# No priorities. Use writeCSS() to add CSS to specific tag attributes.
.css(**kwargs)</code></pre>
<p>As mentioned, you can also add a table with <code class="language-py">create_table()</code>. Make sure the arg rows is a list of lists, even if there's only one row</p>
<pre class="line-numbers"><code class="language-py">createTable(self, heads:list, rows:list, **kwargs)
# heads(list, compulsory): Adds table headers
# rows(list, compulsory) : Takes in a list of lists, each list representing a row
# kwargs(optional) : Adds tag attributes to
with Table() as t:
c = ['foo', 'foo1', 'foo2']
r1 = ['united states', 'croatia', 'austria']
r2 = ['czech', 'denmark', 'canada']
r3 = ['netherlands', 'scotland', 'england']
r = [r1, r2, r3]
t.create_table(heads=c, rows=r, id='table_id')
# Adding CSS
writeCSS(font_family="Arial, Helvetica, sans-serif", border="1px solid #d1d5e8", padding='8px', width='30%')</code></pre>
<p>Output:</p>
<table id="table_id">
<tr>
<th>foo</th>
<th>foo1</th>
<th>foo2</th>
</tr>
<tr>
<td>United States</td>
<td>Croatia</td>
<td>Austria</td>
</tr>
<tr>
<td>Czech</td>
<td>Denmark</td>
<td>Canada</td>
</tr>
<tr>
<td>Netherlands</td>
<td>Scotland</td>
<td>England</td>
</tr>
</table>
</div>
<hr>
<!--Bullets and lists-->
<div id="bullets_and_lists">
<pg_title>Bulleted lists (ordered and unordered)</pg_title>
<p>
Ordered and/or unordered lists can be added with <code class="language-py">bullets()</code> using <code class="language-py">with</code>.
Just enter a list into the argument <code>points</code>, specify the type of the list (ordered or unordered), attributes if necessary, and you're good to go.
It doesn't have a <code class="language-py">.css()</code> function - use one of the three methods to add CSS to it.
</p>
<pre class="line-numbers"><code class="language-py">bullets(ul:bool, points:list, attr=None)
a = ['pt1', 'pt2', 'pt3']
b = ['pt4', 'pt5']
c = ['pt6']
with bullets(ul=False, points=a, attr="start='1' type='i'"):
with bullets(True, b, attr="type='square'"):
pass
with bullets(ul=False, points=c, attr="start='4' type='I'"):
pass</code></pre>
Output:
<ol start="1" type="i">
<li>pt1</li>
<li>pt2</li>
<li>pt3</li>
<ul type="square">
<li>pt4</li>
<li>pt5</li>
</ul>
</ol>
<ol start="4" type="I">
<li>pt6</li>
</ol>
</div>
<hr>
<!--Descriptive list-->
<div id="des_lists">
<pg_title>Adding a description list</pg_title>
<p>
Description lists can be added with <code class="language-py">des_lists()</code>, which takes in argument <code class="language-py">des_list</code> and of course, attributes can be added with <code class="language-py">**kwargs</code>.
Just enter in a list of lists as the first argument, and it will show as a description list.
It is not a context manager-based approach.
</p>
<pre class="line-numbers"><code class="language-py">writeCSS('#d_list', {"margin-left":"40px"})
a = [[['foo'], ['foo1', 'foo2']], [['py', 'py1'], ['PEP', 'PEP8']]]
des_lists(a, "id='d_list'")</code></pre>
Output:
<dl id="d_list">
<dt>foo</dt>
<dd>- foo1</dd>
<dd>- foo2</dd>
<dt>py</dt>
<dt>py1</dt>
<dd>- PEP</dd>
<dd>- PEP8</dd>
</dl>
<p>
Here,
<code class="language-py">[['foo'], ['- foo1', '- foo2']]</code> is the first description list, and <code class="language-py">[['py', 'py1'], ['- PEP', '- PEP8']]</code> is the
second. These two are separated by commas and are subsets of a list that contains them both. The attribute <code class="language-py">id='d_list'</code> was
added to the description list, and CSS was added to the id with <code class="language-py">writeCSS()</code>.
<br>
So get careful with the list arrangement!
</p>
</div>
<hr>
<div id="other_funcs">
<!-- Other functions -->
<pg_title>Other functions</pg_title>
<p>
Python functions/variables or anything can be added onto the web application using Sierra with much ease. However keep in mind, that every
function/CSS/tag, or anything that is to be added to the HTML must come only after <code class="language-py">title()</code>.
<br>
Here's a list of other functions you can use with Sierra:
</p>
<pre class="line-numbers"><code class="language-py">writeWA(text)
# writeWA() can be used to add any text/inline onto the web application.
# This can be used to add text within certain tags.</code></pre>
<p>Here's an example:</p>
<pre class="line-numbers"><code class="language-py">with open_tag('pre'):
writeWA(r"This appears inside the <pre class=""><code> tag")
# Or say you want to add some Bootstrap to your page:
title()
@tag
def link(**kwargs):
pass
@tag
def script(**kwargs):
pass
addFont('Any font link')
# Bootstrap link tags:
link(rel="stylesheet", href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css")
script(src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js")
script(src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js")</code></pre>
<p>Regular HTML escape sequences and glyphs and regular tags like <code class="language-html"><a></code> can be used within the context manager or any functions that involve displaying on the web application, like</p>
<pre class="line-numbers"><code class="language-py">p('HTML <a href="some_link">tag</a> within a paragraph <br> This sentence comes after a break')
autoPrettify()
# It handles tags beautifully, closes unclosed tags, and improves overall look of the HTML inline.
# Use this at the end of all development outside all context managers.
# Using it inside or at a working stage will not work well.
# However if you want to add inline to the HTML after </html>, use autoPrettify(), add inline,
# and THEN use autoPrettify() AGAIN
# Go to this to see the beauty of autoPrettify()</code></pre>
</div>
<hr>
<pg_title>License</pg_title>
<pre class="language-markup"><code>
See <a href="https://github.com/BrainStormYourWayIn/sierra/blob/main/LICENSE">LICENSE</a>
Pandas (pandas) -- table
Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
Copyright (c) 2011-2020, Open source contributors.</code></pre>
</body>
</html>