Merge branch 'master' of ssh://github.com/owncloud/documentation

README.rst

@@ -25,5 +25,5 @@ The ``master`` branch is always the development branch. If a new server version
 Building
 --------
 
-Enter any manual directory, then run ``make html``. The result can be found in the ``_build/html`` subdirectory.
+Make sure that Sphinx is installed (e.g. sudo yum install python-sphinx), then enter any manual directory, then run ``make html``. The result can be found in the ``_build/html`` subdirectory.
 

_shared_assets/themes/owncloud/README.rst

@@ -0,0 +1,89 @@
+========================
+ Sphinx Bootstrap Theme
+========================
+
+This repository integrates the Twitter Bootstrap_ CSS / JavaScript framework
+as a Sphinx_ theme_. A live demo_ is available to preview the theme.
+
+.. _Bootstrap: http://twitter.github.com/bootstrap/
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _theme: http://sphinx.pocoo.org/theming.html
+.. _demo: http://ryan-roemer.github.com/sphinx-bootstrap-theme
+
+
+Installation
+============
+To install the theme, download the theme directory and update your
+configuration
+
+1. Create a "_themes" directory in your project source root.
+2. Get the "bootstrap" themes either as raw files or as a zipfile from
+   the repository.
+
+   a. Most current way is to just clone this repo or download the full
+      repo source and move the "bootstrap" directory to "_themes".
+   b. Alternatively, there are some prepackaged theme zip files (containing
+      only the theme files), which can be read directly by Sphinx. See the
+      repo downloads_ page for available packages. Then download
+      "bootstrap.zip"::
+
+        $ cd /path/to/_themes
+        $ wget https://github.com/downloads/ryan-roemer/sphinx-bootstrap-theme/bootstrap.zip
+
+      In addition to the "current" release, the GitHub zipfiles have either git
+      hash releases (for development builds) or tags for official tagged
+      releases. E.g.::
+
+        bootstrap.zip
+        bootstrap-v0.0.2.zip
+        bootstrap-f51d73491e9bae68eb1b1c57059d9e0ece03d125.zip
+
+3. Edit your configuration file to point to the bootstrap theme::
+
+      # Activate the theme.
+      sys.path.append(os.path.abspath('_themes'))
+      html_theme_path = ['_themes']
+      html_theme = 'bootstrap'
+
+      # (Optional) Use a shorter name to conserve nav. bar space.
+      html_short_title = "Demo"
+
+      # (Optional) Logo. Should be exactly 32x32 px to fit the nav. bar.
+      # Path should be relative to the html_static_path setting (e.g.,
+      # "_static") in source.
+      html_logo = "my_logo.png"
+
+.. _downloads: https://github.com/ryan-roemer/sphinx-bootstrap-theme/downloads
+
+Theme Notes
+===========
+Sphinx
+------
+The theme places the global TOC, local TOC, navigation (prev, next) and
+source links all in the top Bootstrap navigation bar, along with the Sphinx
+search bar on the left side.
+
+The global (site-wide) table of contents is the "Site" navigation dropdown,
+which is a multi-level deep rendering of the ``toctree`` for the entire site.
+The local (page-level) table of contents is the "Page" navigation dropdown,
+which is a multi-level rendering of the current page's ``toc``.
+
+Generally speaking, this is a quick and dirty hack to get the basic theme
+going, so there are likely some oversights and lurking issues. Help and
+bug filings for the project are most welcome.
+
+
+Bootstrap
+---------
+The theme uses Twitter Bootstrap v2.0. You can override any static JS/CSS files
+by dropping different versions in your Sphinx "_static" directory.
+
+
+Licenses
+========
+Sphinx Bootstrap Theme is licensed under the MIT_ license.
+
+Twitter Bootstrap is licensed under the Apache_ license.
+
+.. _MIT: https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/master/LICENSE.txt
+.. _Apache: https://github.com/twitter/bootstrap/blob/master/LICENSE

_shared_assets/themes/owncloud/globaltoc.html

@@ -0,0 +1,4 @@
+<li class="dropdown">
+  <a href="{{ pathto(master_doc) }}" class="dropdown-toggle" data-toggle="dropdown">{{ _('Site') }} <b class="caret"></b></a>
+  <ul class="dropdown-menu globaltoc">{{ toctree(maxdepth=1) }}</ul>
+</li>

_shared_assets/themes/owncloud/layout.html

@@ -0,0 +1,189 @@
+{% extends "basic/layout.html" %}
+{% set script_files = script_files + ['_static/bootstrap.js'] %}
+{% set css_files = [ '_static/style.css', '_static/bootstrap-sphinx.css'] + css_files %}
+
+{# Sidebar: Rework into our Boostrap nav section. #}
+{% macro navBar() %}
+  <div class="navbar navbar-fixed-top">
+    <div class="navbar-inner" style="margin:0;">
+      <div class="container">
+        <a class="brand" href="http://owncloud.org/" title="ownCloud.org" rel=
+        "home"><img src=
+        "http://owncloud.org//wp-content/themes/owncloudorg2/images/logo.png" alt=
+        "ownCloud Logo" /></a>
+
+        <div class="nav-collapse">
+          <div class="menu-header-container">
+            <ul id="menu-header" class="nav">
+              <li id="menu-item-1444" class=
+              "menu-item menu-item-type-post_type menu-item-object-page menu-item-1444">
+              <a href="http://owncloud.org/news/">News</a></li>
+
+              <li id="menu-item-2299" class=
+              "menu-item menu-item-type-post_type menu-item-object-page menu-item-2299">
+              <a href="http://owncloud.org/features/">Features</a></li>
+
+              <li id="menu-item-3417" class=
+              "menu-item menu-item-type-post_type menu-item-object-page menu-item-3417">
+              <a href="http://owncloud.org/about/">About</a></li>
+
+              <li id="menu-item-732" class=
+              "menu-item menu-item-type-post_type menu-item-object-page current-menu-item page_item page-item-14 current_page_item menu-item-732">
+              <a href="http://owncloud.org/support/">Documentation</a></li>
+
+              <li id="menu-item-731" class=
+              "menu-item menu-item-type-post_type menu-item-object-page menu-item-731">
+              <a href="http://owncloud.org/dev/">Developer</a></li>
+
+              <li id="menu-item-6" class=
+              "menu-item menu-item-type-custom menu-item-object-custom menu-item-6">
+              <a target="_blank" href="http://owncloud.com">Commercial &#8594;</a></li>
+            </ul>
+          </div><a href="http://owncloud.org/install" class=
+          "btn btn-success nav-btn">Install</a> <a href="http://demo.owncloud.org" id=
+          "demoheaderbtn" target="_blank" class="btn btn-info nav-btn">Try it!</a>
+        </div>
+      </div>
+    </div>
+  </div>
+  {#
+  <div id="navbar" class="navbar navbar-fixed-top">
+    <div class="navbar-inner">
+      <div class="container-fluid">
+        <a class="brand" href="{{ pathto(master_doc) }}">{{ project|e }}</a>
+        <span class="navbar-text pull-left"><b>{{ version|e }}</b></span>
+          <ul class="nav">
+            <li class="divider-vertical"></li>
+            {% block sidebartoc %}
+              {% include "globaltoc.html" %}
+              {% include "localtoc.html" %}
+            {% endblock %}
+            {% block sidebarrel %}
+              {% include "relations.html" %}
+            {% endblock %}
+            {% block sidebarsourcelink %}
+              {% include "sourcelink.html" %}
+            {% endblock %}
+          </ul>
+          {% block sidebarsearch %}
+            {% include "searchbox.html" %}
+          {% endblock %}
+          </ul>
+        </div>
+      </div>
+    </div>
+  </div>
+  #}
+{% endmacro %}
+
+{%- block extrahead %}
+<script type="text/javascript">
+(function () {
+  /**
+   * Patch TOC list.
+   *
+   * Will mutate the underlying span to have a correct ul for nav.
+   *
+   * @param $span: Span containing nested UL's to mutate.
+   * @param minLevel: Starting level for nested lists. (1: global, 2: local).
+   */
+  var patchToc = function ($ul, minLevel) {
+    var findA;
+
+    // Find all a "internal" tags, traversing recursively.
+    findA = function ($elem, level) {
+      var level = level || 0,
+        $items = $elem.find("> li > a.internal, > ul, > li > ul");
+
+      // Iterate everything in order.
+      $items.each(function (index, item) {
+        var $item = $(item),
+          tag = item.tagName.toLowerCase(),
+          pad = 15 + ((level - minLevel) * 10);
+
+        if (tag === 'a' && level >= minLevel) {
+          // Add to existing padding.
+          $item.css('padding-left', pad + "px");
+          console.log(level, $item, 'padding-left', pad + "px");
+        } else if (tag === 'ul') {
+          // Recurse.
+          findA($item, level + 1);
+        }
+      });
+    };
+
+    console.log("HERE");
+    findA($ul);
+  };
+
+  $(document).ready(function () {
+    // Add styling, structure to TOC's.
+    $(".dropdown-menu").each(function () {
+      $(this).find("ul").each(function (index, item){
+        var $item = $(item);
+        $item.addClass('unstyled');
+      });
+      $(this).find("li").each(function () {
+        $(this).parent().append(this);
+      });
+    });
+
+    // Patch in level.
+    patchToc($("ul.globaltoc"), 2);
+    patchToc($("ul.localtoc"), 2);
+
+    // Enable dropdown.
+    $('.dropdown-toggle').dropdown();
+  });
+}());
+</script>
+{% endblock %}
+
+{% block header %}{{ navBar() }}{% endblock %}
+
+{# Silence the sidebar's, relbar's #}
+{% block sidebar1 %}{% endblock %}
+{% block sidebar2 %}{% endblock %}
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+
+{%- block content %}
+<div class="container">
+  <div class="content">
+    <div class="page-header">
+      <h1><a href="#">Documentation Centre</a></h1>
+
+      <form role="search" method="get" class="headersearch" id="searchform" action=
+      "#">
+        <input type="text" value="" name="s" id="s" /> <input type="submit" id=
+        "searchsubmit" class="btn" value="Search" />
+      </form>
+    </div>
+    {% block body %}{% endblock %}
+  </div>
+</div>
+{%- endblock %}
+
+{%- block footer %}
+<footer class="footer">
+  <div class="container">
+    <p class="pull-right"><a href="#">Back to top</a></p>
+    <p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}<br/>
+      {%- endif %}
+    {%- endif %}
+    {%- if last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
+    {%- endif %}
+    {%- if show_sphinx %}
+      {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br/>
+    {%- endif %}
+    </p>
+  </div>
+</footer>
+{%- endblock %}
+

_shared_assets/themes/owncloud/localtoc.html

@@ -0,0 +1,5 @@
+<li class="dropdown">
+  <a href="#" class="dropdown-toggle" data-toggle="dropdown">{{ _('Page') }} <b class="caret"></b></a>
+  <ul class="dropdown-menu localtoc">{{ toc }}</ul>
+  <!--<span class="localtoc">{{ toc }}</span>-->
+</li>

_shared_assets/themes/owncloud/relations.html

@@ -0,0 +1,8 @@
+{%- if prev %}
+  <li><a href="{{ prev.link|e }}"
+         title="{{ _('previous chapter') }}">{{ "&laquo;"|safe }} {{ prev.title }}</a></li>
+{%- endif %}
+{%- if next %}
+  <li><a href="{{ next.link|e }}"
+         title="{{ _('next chapter') }}">{{ next.title }} {{ "&raquo;"|safe }}</a></li>
+{%- endif %}

_shared_assets/themes/owncloud/searchbox.html

@@ -0,0 +1,7 @@
+{%- if pagename != "search" %}
+<form class="navbar-search pull-right" style="margin-bottom:-3px;" action="{{ pathto('search') }}" method="get">
+  <input type="text" name="q" placeholder="Search" />
+  <input type="hidden" name="check_keywords" value="yes" />
+  <input type="hidden" name="area" value="default" />
+</form>
+{%- endif %}

_shared_assets/themes/owncloud/sourcelink.html

@@ -0,0 +1,4 @@
+{%- if show_source and has_source and sourcename %}
+  <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">{{ _('Source') }}</a></li>
+{%- endif %}

_shared_assets/themes/owncloud/static/bootstrap-sphinx.css_t

@@ -0,0 +1,24 @@
+/*
+* bootstrap-sphinx.css
+* ~~~~~~~~~~~~~~~~~~~~
+*
+* Sphinx stylesheet -- Twitter Bootstrap theme.
+*/
+
+body {
+  padding-top: 52px;
+}
+
+.navbar .brand {
+  color: #FFF;
+  text-shadow: #777 2px 2px 3px;
+}
+
+{%- block sidebarlogo %}
+  {%- if logo %}
+.navbar h3 a, .navbar .brand {
+  background: transparent url("{{ logo }}") no-repeat 22px 3px;
+  padding-left: 62px;
+}
+  {%- endif %}
+{%- endblock %}

_shared_assets/themes/owncloud/theme.conf

@@ -0,0 +1,5 @@
+# Twitter Bootstrap Theme
+[theme]
+inherit = basic
+stylesheet = style.css
+pygments_style = tango

developer_manual/configfile.rst

@@ -0,0 +1,27 @@
+Config file
+===========
+
+Using alternative app directories
+---------------------------------
+
+ownCloud can be set to use a custom app directory in /config/config.php. Customise the following code and add it to your config file:
+
+.. code-block:: php
+
+  'apps_paths' =>
+  	array (
+  		0 =>
+  		array (
+  			'path' => OC::$SERVERROOT.'/apps',
+  			'url' => '/apps',
+  			'writable' => true,
+  		),
+  		1 =>
+  		array (
+  			'path' => OC::$SERVERROOT.'/apps2',
+  			'url' => '/apps2',
+  			'writable' => false,
+  		),
+  	),
+	
+ownCloud will use the first app directory which it finds in the array with 'writable' set to true.

developer_manual/debugging.rst

@@ -0,0 +1,53 @@
+Debugging
+=========
+
+Debug mode
+----------
+
+When debug mode is enabled ownCloud, a variety of debugging features are enabled - see debugging documentation. Add the following to the very end of /config/config.php to enable it::
+
+  define( "DEBUG", 1);
+
+
+Identifying errors
+------------------
+
+ownCloud uses custom error PHP handling that prevents errors being printed to webserver log files or command line output. Instead, errors are generally stored in ownCloud's own log file, located at: **/data/owncloud.log**
+
+
+Debugging variables
+-------------------
+
+You should use exceptions if you need to debug variable values manually, and not alternatives like trigger_error() (which may not be logged).
+
+e.g.:
+
+.. code-block:: php
+  
+  <?php throw new \Exception( "\$user = $user" ); // should be logged in ownCloud ?>
+
+not:
+
+.. code-block:: php
+  
+  <?php trigger_error( "\$user = $user" ); // may not be logged anywhere ?>
+
+To disable custom error handling in ownCloud (and have PHP and your webserver handle errors instead), see Debug mode.
+
+
+Debugging Javascript
+--------------------
+
+By default all Javascript files in ownCloud are minified (compressed) into a single file without whitespace. To prevent this, see Debug mode.
+
+
+Debugging HTML and templates
+----------------------------
+
+By default ownCloud caches HTML generated by templates. This may prevent changes to app templates, for example, from being applied on page refresh. To disable caching, see Debug mode.
+
+
+Using alternative app directories
+---------------------------------
+
+It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different versions of applications. See the configuration file documentation for details.

developer_manual/index.rst

@@ -1,7 +1,7 @@
 ownCloud Developers Manual
 **************************
 
-Short synopsis of the manual goes here.
+This is the ownCloud documentation. More information and source code is at the `Git repository <https://github.com/owncloud/documentation>`_.
 
 Contents
 ========
@@ -10,6 +10,8 @@ Contents
    :maxdepth: 2
 
    introduction
+   debugging
+   configfile
    unittests
 
 

user_manual/connecting/webdav.rst

@@ -2,14 +2,15 @@ Mounting ownCloud via WebDAV
 =============================
 
 All major operating systems allow for mounting a users ownCloud via WebDAV,
-a HTTP extension as specified in :rfc:`2518`. This chapter describes how to setup
-WebDAV on different operating systems.
+a HTTP extension as specified in :rfc:`2518`. This chapter describes how to 
+setup WebDAV on different operating systems.
 
 Windows
 -------
 
-On Windows, you can assign ownCloud a drive letter, which allows browsing
-files stored on ownCloud like a local hard drive. 
+On Windows, you can assign ownCloud a drive letter.  This allows you to 
+browse files stored on an ownCloudserver the way you would files stored in a 
+mapped network drive. 
 
 Using this feature requires network connectivity. If you want to store
 your files offline, use the ownCloud Client to sync all files on your
@@ -20,7 +21,8 @@ ownCloud to one or more directories of your local hard drive.
           Basic Authentication in the Windows Registry. The procedure is
           documented in KB841215_ and differs between Windows XP/Server 2003
           and Windows Vista/7. Please follow the Knowledge Base article
-          before proceeding. 
+          before proceeding, and follow the Vista instructions if you run 
+          Windows 7. 
 
 Mapping via the command line
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~