From 528201a25b84b0d2ac6d3263d7c25e3677a27316 Mon Sep 17 00:00:00 2001 From: pranavr2003 Date: Mon, 19 Jul 2021 15:13:14 +0530 Subject: [PATCH] Update README.md --- README.md | 258 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 136 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 74ef349..0766d18 100644 --- a/README.md +++ b/README.md @@ -6,168 +6,181 @@ ![GitHub](https://img.shields.io/github/license/BrainStormYourWayIn/sierra?color=blue) -Sierra is a Python native engine for web development, which makes templating for the backend easy, as well as have full control on your frontend. You can now develop your web application purely in Python, taking full advantage of its powerful functionalities with simple and elegant syntax. +Sierra is a Python library to write HTML and CSS in pure Python using the DOM API in a simple yet elegant manner. Take advantage of Python's powerful +functionalities with ease. Loops, variables, functions, libraries - you name it, you have it. -This was in part inspired by [Dominate](https://github.com/Knio/dominate), but has support for CSS styling attributes, better syntax, more use cases and many more functionalities +Here are a few advantages of using Sierra over other Python libraries that use the DOM API: -It can be used standalone in developing web applications +- Out-of-the-box support for all CSS styling attributes for all tags +- Display a table by simply putting in a CSV file +- Create your own tag functions with absolute ease using `@tag` and `@CmTag`. You can decide their behavior and use them within content-managers too +- Improvement in the arrangement look of the code and intelligent handling of tags with +`autoPrettify()` - Powered by bs4 and a feature like no other -You can also use this as an alternative to jinja or Django's templating or any other templating engine, or even use it along with one - -It's got features like displaying a table on the web application by loading in a .csv file, adding a bulleted list (ol/ul) by just passing in a list, automatic support for CSS styling arguments and more! You can use for loops, variables, functions - you name it, you have it, with Sierra. Improvement in the overall look of the code and intelligent handling of tags with `autoPrettify()`, a feature like no other. Harness the power of Python for your web applications! +You may also use this as a templating engine, although jinja and Django's templating engine is strongly recommended over this ________________________________ ## Documentation - **Check out the [documentation of Sierra](https://brainstormyourwayin.github.io/sierra.github.io/)** -- **Check out a [few examples](https://github.com/BrainStormYourWayIn/sierra_examples/) of its use** - -> The examples mentioned above is a simple bare-boned book search engine created with requests, bs4, Flask and Sierra; and the documentation of Sierra, which was written with Sierra standalone - -________________________________ -This is intended for used in developing less resource-heavy web applications (since this hasn't been tested with any resource-heavy ones) which involve a good amount of Python code, and if you want to work exclusively on Python without using another templating engine (jinja, Django's templating). Although you may use this with them if the use case suits you. - -________________________________ -**Have a look at `src/sierra/custom_tags.py` and `release_prots.py` for a sneak-peek on the next release updates. We got some things going on there!** ________________________________ +**Installation and Upgrade** -## Example - -Using this with Flask makes life easier if you're developing web applications with just HTML and CSS. Adding JS with manual functions will be supported by Sierra in the coming release(s) - -Here's a little example for this: - + pip install sierra + + pip install --upgrade sierra + +Starting off is pretty simple and straightforward: ```python -from flask import Flask, render_template from sierra import * + +title('Hello World!') +``` + +The `title()` function at the start is mandatory, since it commences the HTML and the CSS file, which is created in the working directory upon execution on the code. -app = Flask(__name__) - -def the_template(): - title('Some title', templating=True) # Set templating to True if you're using Flask - head('Just a heads up', 'h2') - openBody() - -def adding_table(): - - the_template() - with div(None, attr="id='div_id'"): - - with startTable() as st: # Creating a table within the
tag +You can create custom tag functions with @tag and @CmTag with just three lines of code. Say you want to create a function for <meta>: +```python +@tag +def meta(**kwargs): + pass - st.getTable('path/to/file.csv') - st.css(font_family="Arial, Helvetica, sans-serif", border="1px solid #d1d5e8", padding='8px', width='20%') - - - autoPrettify() - write_to_template('index1.html') - -def pre_and_unordered_list(): - - the_template() - with div(div_class='description_list'): - - with open_tag('pre') as pr: - writeWA("Some text within the 
 tag")
-            pr.css(background_color="#e1e8e3")
-
-        with section(sec_class='unordered_list') as s:                 # Creating section inside div
-            ul_list = ['This', 'is', 'an', 'unordered', 'list']        
-            with bullets(ul=True, points=ul_list):      
-                pass        
-
-    autoPrettify()
-    write_to_template('index2.html')
-
-@app.route("/adding_table")
-def show_adding_table():
-    adding_table()
-    return render_template('index1.html')
-
-@app.route("/pre_and_unordered_list")
-def show_pre_and_unordered_list():
-    pre_and_unordered_list()
-    return render_template('index2.html')
-
-if __name__ == '__main__':
-    app.run()
+# Using them
+    
+meta(name="description", content="This is some description")
+meta(name="viewport", content="width=device-width", initial_scale=1.0)
 ```
 
-First, the directory structure needs to get sorted before running this. Run the code outside of `templates/`.
+Underscores are used for hyphens (same applies to CSS) and Python-conficting arguments are prefixed with a double underscore.
 
-Here with `write_to_template()`, you can name your HTML file and call the function which takes only that argument to write the file into the `templates/` folder. `style.css` is automatically put into `static/` when this function is called. 
+Using argument `text` inside of a function defined in `@tag` will create a tag that opens, enters text, and closes. Something like this:
+```python
+@tag
+def script(**kwargs):
+    pass
+script(__async="", src="some_src", text="some_text")
+```
+Is the equivalent of:
+```html
+
+```
+Want to add some JS? Simple enough. Just create a function for the <script> tag with a context manager behavior using `@CmTag` and you're golden.   
+```python
+@CmTag
+def script(**kwargs):
+    pass
 
-In `title()`, set the argument `templating` to True, if Sierra is being used to template with Flask
+# Here I'll be replicating the script needed to add Google Analytics to a webpage
 
-Of course, you can also define the functions in separate files and import it.   
+with script(__aync="", src="https://www.googletagmanager.com/gtag/js?id=UA—XXXXXXXX-X"):
+    pass
+    
+with script():
+
+    writeWA('''
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'UA—XXXXXXXX-X');
+  ''')
+```
+This is the equivalent of:
+```html
+
 
-Sierra can also be used standalone without Flask, like this:
+
+```
+`writeWA()` writes text entered into it into the HTML file as it is. 
 
+You can add fonts using `addFont()`
+```python
+addFont("https://fonts.googleapis.com/css2?family=Roboto&display=swap")
+```
+Once things at the `` of the HTML are settled (CSS is automatically linked), begin the body of the HTML with
 ```python
-from sierra import *
-
-title('The title goes here')
-head('Sierra!', type='h2', color="#0388fc")
 openBody()
-
-with open_tag('newTag'):      
-
-    with div('someClass') as d:     
-        p('Some text within the div')                   
-        d.css(background_color='rgb(211, 111, 121)')          # Adding CSS to the div
-        
-        with section('anotherClass', "id='some_id'"):         # Creating section within the div within 'newTag'
-            with startTable() as st:
-                st.getTable(/path/to/file.csv, attr="id='table_id'")   
-                
-                with cTags('#table_id') as t:
-                    t.css(font_family="Arial, Helvetica, sans-serif", border="1px solid #d1d5e8", padding='8px', width='20%')     
-                    
-            p("This is a paragrah within a section, which is within a div tag and comes afer the table")
-
-    with image(src='sierra.jpg'):    
-        i.show()                        # Displaying an image
-        i.css(opacity=1.2)              # Adding CSS to it
-         
-    p("This is a paragraph that doesn't come under any div or a section, but comes under . Simple stuff, really!")
-    
-autoPrettify() 
+# You can add any number of styling arguments to the body within openBody()
+openBody(background_color='yellowgreen', opacity='0.9')
+```
+You can create `div` and `section` tags this way:
+```python
+with div(__class="some_class") as d:
+    p('This is a paragraph!')
+    d.css(background_color="#5886d1")
 ```
+Let's break this down but-by-bit:  
+First, we start a `div` with a context manager behavior and give it an attribute `__class`, which is essentially the tag attribute `class` (remember Python-conflicting) arguments are prefixed by a double underscore.
 
-### See the [documentation](https://brainstormyourwayin.github.io/sierra.github.io/) for more
+`p()` is a function, as the name suggests, to add a `
` tag. You can give the tag attributes with `**kwargs`, if you like.   
+`p('Hello World!', __class='p_class')` is the same as `
Hello World!
`
 
-________________________________
+After the paragraph, there's a `d.css()`. This adds CSS to the `class` mentioned within `div()`. If a `class` is mentioned, CSS is added to that class as the first priority. If an `id` is mentioned, CSS is added to that `id` as a second priority. If none of both are mentioned, CSS is just added to `div`.
 
-## Installation
+The behavior of `div` shown above also applies to `section`.
 
-To download the library:
+You can open a new tag with `Tag()`
+```python
+with Tag('some_tag', id='some_id') as t:
+    p('A paragraph in ')
+    t.css(color='blue')
+```
+Although here, `.css()` behaves differently. It is independent of tag attributes, meaning CSS is added directly to the tag mentioned, which is `some_tag`
 
-    pip install sierra
+To add CSS to a specific attribute in the tag, use `writeCSS()`
+```python
+writeCSS(tag_name, **kwargs)
 
-________________________________
+writeCSS("#some_id", color='blue')
+```
+This adds CSS to the `some_id`.
 
-## Upgrade
+You can add a table to the HTML page by inputting in a CSV file this way:
+```python
+with Table() as t:
+    t.get_table("path/to/file.csv")   # Add attributes with **kwargs here
+    t.css(border="1px solid black")   # Use writeCSS to add CSS to a specific attribute
+```
+There are MANY more functionalities to Sierra that you can see from the [documentation](https://brainstormyourwayin.github.io/sierra.github.io/)
 
-To upgrade the library:
+At the end of all development with Sierra, use
+```python
+autoPrettify()
+```
+It takes in no arguments, but provides SO much to the code.
 
-    pip install --upgrade sierra
+Try running this WITHOUT `autoPrettify()` at first and see `index.html`, and then WITH it, and see `index.html` again:
 
-________________________________
+```python
+title('Some title')
+head('Some header', 'h2')
 
-### Upcoming (in order of priority):
+openBody()
 
-- Enable auto-introduction of custom tags tags like `span`, `label`, `input` or anything, with decorators (See `release_prots.py`)
-- In-memory storage for the HTML and CSS file (See `release_prots.py`)
-- Deprecate cTags() and just introduce a new function called css(), since adding CSS with a class is longer than simply doing css('.some_class', color='blue',           font_size='20px')
-- Deprecate the attr argument and instead use **kwargs to add tag attributes
-- Add an option for in-memory storage, see release_prots.py
-- Use `kwargs` to add tag attributes
-- Change startTable and createTable to start_table and create_table
+with div(__class='some_class') as d:
+    p('Some text that falls inside the division')
+    d.css(background_color='black')
+    
+    with section(id='some_id') as sec:
+        p('Some text within a section within a div')
+        sec.css(background_color='red')
+        
+    with bullets(ul=True, points=['foo', 'bar', 'baz']):
+        pass
+
+writeCSS('p', color='white')
 
-**See `release_prots.py`**
+autoPrettify()         # --> Try without this and see index.html, then with this and have a look at index.html again
+```
 
 ________________________________
 
@@ -179,6 +192,7 @@ Email: brainstormyourwayin@gmail.com
 
 ________________________________
 
+**Open with GitPod**
 
 [![GitPod](https://www.gitpod.io/svg/media-kit/logo-dark-theme.svg)](https://gitpod.io/#https://github.com/BrainStormYourWayIn/sierra/)