Commits

Jaiditya committed 23a7395

Theme delevopment documentation added

  • Participants
  • Parent commits ea19b98

Comments (1)

  1. Thomas Waldmann

    maybe rather don't create new subfolders in devel/, esp. if you only have 1 file to put there.

    also, i think i already noted that it is neither needed nor advisable to document 3rd party stuff. stylus has own documentation, so you just need to point to it, not repeat it. we have to concentrate on documenting OUR stuff and try to not bloat our docs with other stuff.

Files changed (1)

docs/devel/theme/development.rst

+========================
+Creating a custom Theme:
+========================
+To create a theme one needs to put a custom theme into the theme folder. A custom theme is simply a folder containing static media (like CSS files, images, and JavaScript) and Jinja2 templates, with some metadata. A theme folder should look something like this:
+
+my_theme/
+    info.json
+    license.txt
+    templates/
+        layout.html
+        index.html
+    static/
+        common.css (this file is generated using main.styl)
+        stylus/
+            main.styl
+
+The info.json file contains the theme’s metadata, so that MoinMoin can provide a nice theme switching interface. license.txt is optional and contains the full text of the theme’s license. static is served directly to clients, and templates contains the Jinja2 template files.
+
+MoinMoin has a set of default templates which are automatically used if a theme does not have some specific template file (or does not have any templates at all). Thus one can even make a custom theme without any template just by adding a static folder and json file.
+
+Templating:
+===========
+Jinja2 is used as the templating engine.
+
+All themes are based on a common parent base.html, from which layout.html (file which sets the layout) of each theme is extended. This layout.html is then extended further in the child templates of the theme.
+
+@extend "base.html"  // added at start of each layout.html
+@extend "layout.html"  // added at the start of child templates
+
+For more details about templating read Jinja2 docs (http://jinja.pocoo.org/docs/templates/). 
+
+Styling a Theme:
+================
+A static folder is present in each theme which contains theme specific css, js and images along with default static folder which contains common css, js and images (e.g. logos) . To change/add a static file one has to decide whether the change is global or specific to one theme and make changes accordingly.
+
+CSS styling: 
+------------
+Styling of a theme is done using CSS, "common.css" is present in each theme's static folder and is generated using the Stylus CSS preprocessor. A single "main.styl" which includes other CSS and Stylus files is used to generate "common.css" using the following command (invoke it in the stylus/ folder):
+
+stylus --include-css --compress < main.styl > ../common.css
+
+main.styl comprises of: 
+    notice.css - includes comments with notice regarding automatically generated css and licensing
+    reset.css - reset all browser-specific default to have common defaults everywhere
+    pygments_default.css - auto-generated by pygmentize -S default -f html >pygments_default.css
+    smileys.css - smileys used by moin wiki parser (and maybe others)
+    admonitions.styl - admonitions used by moin wiki parser (and maybe others)
+    userstyles.css - user styles used by moin wiki parser (and maybe others) like red/green/solid/dashed/comment...
+    color_palette.styl - color have been used from the color palette 
+    mime_type_icons.styl - mime type icons
+    moin_diff.styl - moin diff styling
+
+Writing Stylus Code:
+--------------------
+Writing Stylus code is similar to writing css, just without all the braces, colons and semicolons::
+
+    /* main.styl */
+    h1 {
+      color: #573960;
+    }
+    /* omit brackets */
+    h1
+      color: #573960;
+    /* omit colons and semi-colons */
+    h1
+      color #573960
+
+Using variations in same style sheet is also allowed. So following will not give any error. (avoide using different style in a single style sheet its not a good practice)::
+    
+    h1 {
+      color #573960
+    }
+    h2
+      font-size: 1.8em
+
+Stylus also allows use of Variables, Functions, Operators, Nesting, Importing, Inheritance and Mixins. For more about stylus you can refer Stylus docs (http://learnboost.github.com/stylus/).
+
+Color Management:
+-----------------
+For color management a color palette is defined and all colors used in the theme are taken from that color palette. In order to change a color one only needs to change the definition of the color in "color_palette.styl" and then regenerate the "common.css".
+
+Template Management:
+====================
+Duplication of content should be avoided as much as possible. "layout.html" is used for a general layout (without itemviews) and "show.html" (it is extended from layout.html) is used for theme specific layout (with itemviews). With these as parents further child templates are extended accordingly.
+
+layout.html - for templates without itemviews
+show.html - for templates with itemviews