Docs - first draft

Author: navilan

.gitignore

@@ -0,0 +1,19 @@
+*~
+*.pyc
+.DS_Store
+deploy
+deploy/*
+*.cprof
+*.profile
+*.log
+pylint*
+*.tmproj
+test_site
+dist
+build
+*egg*
+.idea
+PYSMELLTAGS
+.noseids
+*.tar.gz
+.hyde_deps

content/commandline.html

@@ -0,0 +1,162 @@
+===
+title: Command Line
+subtitle: working with hyde
+created: 2011-01-27 11:02:43
+===
+
+§§ blurb
+
+The hyde command line supports three subcommands:
+
+1. create - Initializes a new site at a given path
+2. gen - Generates the website to a configured deploy folder
+3. serve - Starts a local http server that regenerates based on the requested file
+
+§§ /blurb
+
+## The create command
+
+Creates a new hyde website.
+
+~~~sh~~~
+hyde create
+
+hyde [-s </site/path>] [-v] create [-l <layout>] [-f] [-h]
+~~~~~~~~
+
+`-s SITEPATH, --sitepath SITEPATH`
+:   Where the site must be created. If this path is not empty then the `-f`
+    option must be specified to overwrite the site.
+
+    *Optional* - defaults to current working directory.
+
+`-f, --force`
+:   Specifying this option will overwrite files and folders at the given
+    site path.
+
+    *Optional* - If the target directory is not empty, hyde will throw an
+    exception unless this is specified.
+
+`-l LAYOUT, --layout LAYOUT`
+:   The name of the layout to use for creating the initial site. Hyde currently
+    has three layouts: `basic`, `test` and `doc`.
+
+    While basic and test are really barebones, doc is the one that generates
+    this documentation and is completely usable. Hyde will get more layouts
+    over time.
+
+    Hyde tries to locate the specified layout in the following folders:
+
+    1.  In `layouts` folder under the path specified by the `HYDE_DATA`
+    environment variable
+    2.  In `layouts` folder under hyde
+
+    *Optional* - defaults to `basic`
+
+`-v, --verbose`
+:   Logs detailed messages to the console.
+
+    *Optional* - shows only essential messages if this option is omitted.
+
+`-h`
+:   Displays the help text for the `create` command.
+
+Assuming the `HYDE_DATA` environment variable is empty and the folder
+`~/test` is empty, the following command will create a new hyde site
+at `~/test` with the contents of `layouts/doc` folder:
+
+~~~sh~~~
+hyde -s ~/test create -l doc
+~~~~~~~~
+
+## The generate command
+
+Generates the given website.
+
+~~~sh~~~
+hyde gen
+
+hyde [-s </site/path>] [-v] gen [-d </deploy/path>] [-c <config/path>] [-h]
+~~~~~~~~
+
+`-s SITEPATH, --sitepath SITEPATH`
+:   The path to the site to be generated.
+
+    *Optional* - defaults to current working directory.
+
+`-d DEPLOY_PATH, --deploy-path DEPLOY_PATH`
+:   Location where the site should be generated. This option overrides any
+    setting specified in the hyde [configuration][]. The path is assumed to
+    be relative to the site path unless a preceding path separator is found.
+
+    *Optional* - Uses what is specified in the config file. The default option
+    in the configuration file is: `deploy` folder under the current site path.
+
+
+`-c CONFIG, --config-path CONFIG`
+:   This is used for specifying an alternate configuration file to use for
+    generating the site. This is useful if you have two different configurations
+    for you production versus development websites.
+
+    The path is assumed to be relative to the site path unless a preceding path
+    separator is found.
+
+    *Optional* - defaults to `site.yaml`
+
+`-v, --verbose`
+:   Logs detailed messages to the console.
+
+    *Optional* - shows only essential messages if this option is omitted.
+
+`-h`
+:   Displays the help text for the `gen` command.
+
+The following command will use `production.yaml` as the configuration file and
+generate the website at `~/test` to `~/production_site` directory.
+
+~~~sh~~~
+cd ~/test
+hyde gen -c production.yaml -d ~/production_site
+~~~~~~~~
+
+## The serve command
+
+Starts the built in web server that also regenerates based on the request if there are
+changes.
+
+~~~sh~~~
+hyde serve
+
+hyde [-s </site/path>] [-v] gen [-d </deploy/path>] [-c <config/path>] [-h]
+~~~~~~~~
+
+`-s SITEPATH, --sitepath SITEPATH`
+`-d DEPLOY_PATH, --deploy-path DEPLOY_PATH`
+`-c CONFIG, --config-path CONFIG`
+
+:   Since the `serve` command auto generates if there is a need, it needs
+    the same parameters as the `gen` command. The above parameters serve
+    the same purpose here as in the `gen` command.
+
+`-a ADDRESS, --address ADDRESS`
+
+:   The address to serve the website.
+
+    *Optional* - defaults to `localhost`
+
+`-p PORT, --port`
+
+:   The port to serve the website.
+
+    *Optional* - defaults to `8080`
+
+`-h`
+
+:   Displays the help text for the `serve` command.
+
+    The following command will serve the website at `http://localhost:8181`
+
+~~~sh~~~
+cd ~/test
+hyde serve -p 8181
+~~~~~~~~

content/configuration.html

@@ -0,0 +1,161 @@
+===
+title: Configuration
+subtitle: change hyde to match your style
+created: 2011-01-28 01:30:05
+===
+
+§§ blurb
+
+Hyde is configured using one or more `yaml` files. On top of all
+the niceties `yaml` provides out of the box, hyde also adds a few
+power features to manage complex websites.
+
+If a site has a `site.yaml` file in the root directory it is used
+as the configuration for generating the website. This can be
+overridden by providing a command line option. See the
+[command line reference][commandline] for details.
+
+§§ /blurb
+
+## Inheritance
+
+Configuration files can inherit from another file using the
+`extends` option.
+
+For example, the following configuration will inherit all properties
+from `site.yaml` and override the `mode` property.
+
+~~~yaml~~~
+extends: site.yaml
+mode: production
+~~~~~~~~~~
+
+This is useful for customizing the site to operate in different modes.
+For example, when running locally you may want your media files to
+come from `/media` but on production you may have a subdomain and want
+the media to come from `http://abc.example.com/media`.
+
+This can be accomplished by creating an _extended_ configuration file and
+overriding the media_url property. For a real world example, you can take
+a look at the [source of this documentation][hydedocpages].
+
+## Paths & Urls
+
+The following path & url properties can be defined for use in templates:
+
+`media_root`
+:   The root path where media files(images, css, javascript etc.,)
+    can be found. This may be used by plugins for special processing.
+    If your website does not have a folder that contains all media,
+    you can safely omit this property.
+
+    _Optional_. Default: `media`
+
+`media_url`
+:   The url prefix for serving media files. If you are using a CDN like
+    Amazon S3 or the Rackspace cloud and host all your media files from
+    there, you can make use of this property to specify the prefix for
+    all media files.
+
+    _Optional_. Default: `/media`
+
+`base_url`
+:   The base url from which the site is served. If you are hosting the
+    website in a subdomain or as part of a larger website, you can specify
+    this property to indicate the path of this project in your website.
+
+    _Optional_. Default: `/`
+
+`deploy_root`
+:   Where the generated files should go. This can either be a relative
+    path from the root of the site source or an absolute path. Note that
+    this can also be overridden in the [command line][commandline] using
+    the `-d` option.
+
+## Plugins & templates
+
+`template`
+:   The template engine to use for processing the website can be specified
+    in the configuration file as a python class path. Currently no other
+    templates apart from `Jinja2` are supported, so the `template` setting
+    is a NOOP at the moment.
+
+    _Optional_. Default: `hyde.ext.templates.jinja.Jinja2Template`
+
+`plugins`
+:   Plugins are specified as list of python class paths. Events that are
+    raised during the generation of the website are issued to the plugins
+    in the same order as they are listed here. You can learn more about
+    how the individual plugins themselves are configured in the
+    [plugin documentation][plugins].
+
+    _Optional_. Default: No plugins are loaded.
+
+    The following configuration option would load the metadata plugin
+    and the blockdown plugin and execute events in the same order.
+
+    ~~~yaml~~~
+    plugins:
+        - hyde.ext.plugins.meta.MetaPlugin
+        - hyde.ext.plugins.blockdown.BlockdownPlugin
+    ~~~~~~~~~~~
+
+## Context
+
+The context section contains key / value pairs that are simply passed
+on to the templates
+
+_Optional_. Default: No context variables are defined.
+
+For example, given the following configuration, the statement
+`{%raw%}{{hyde.current_version}}{%endraw%}` in any template
+will output `0.6`.
+
+~~~yaml~~~
+context:
+    hyde:
+        current_version: 0.6
+~~~~~~~~~~~
+
+## Providers
+
+Providers are special constructs used to import data into the context.
+For example, data from a database can be exported as `yaml` and imported
+as providers.
+
+For example, consider the following snippet:
+
+~~~yaml~~~
+context:
+    providers:
+        versions: hyde-versions.yaml
+~~~~~~~~~~~
+
+This would import the data in `hyde-versions.yaml` into `context[versions]`.
+This data can be used directly in templates in this manner:
+`{%raw%}{{ versions.latest }}{%endraw%}`.
+
+
+## Markdown
+
+Extensions and extension configuration for markdown can be configured in the
+`markdown` property. You can read about markdown extensions in
+[python markdown documentation][pymarkdown].
+
+The following configuration:
+
+~~~yaml~~~
+markdown:
+    extensions:
+        - def_list
+        - tables
+        - headerid
+~~~~~~~~~~
+
+will use the def_list, tables and headerid extensions in python markdown.
+
+
+[commandline]: [[commandline.html]]
+[plugins]: [[plugins.html]]
+[pymarkdown]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions
+[hydedocpages]: https://github.com/hyde/hyde/blob/master/hyde/layouts/doc/pages.yaml