Style & cleanups

README.md

@@ -0,0 +1,36 @@
+# Syncthing Docs
+
+This repo is the source behind http://docs.syncthing.net/.
+
+# Editing
+
+To edit the documentation you need a GitHub account. Once you have created one
+and logged in, you can edit any page by navigating to the corresponding file
+and clicking the edit (pen) icon. This will create what is called a "fork" and
+a "pull request", which will be approved by one of the existing documentation
+team members. Once you've made a contribution or two, you can be added to the
+documentation team and perform edits without requiring approval.
+
+In the long run, learning to use git and running
+[Jekyll](http://jekyllrb.com/) on your computer is beneficial.
+
+# Structure
+
+The documentation is divided into an index page (`index.md`) and various subsections. The sections are:
+
+ - Introductory information in `_intro`.
+ - Information for users in `_users`.
+ - Information for developers in `_dev`.
+
+Each page has what is called a "front matter", which looks something like:
+
+ ```
+ ---
+ title: Getting Started
+ weight: 0
+ ---
+ ```
+
+ This sets, at minimum the title of the page. There are various other attributes that can be added, the most common ones being `weight` (to adjust the order of pages in the index; lower number gets sorted higher up) and `nav` (set `nav: false` to have a page not be listed in the index).
+
+The rest of the page is in [Markdown format](https://help.github.com/articles/github-flavored-markdown/).

_static/syncthing.css

@@ -1,6 +1,10 @@
-p {
+.rst-content p, .rst-content p.admonition-title, .rst-content li, .rst-content table.docutils td,
+.rst-content table.docutils th, .rst-content code, .rst-content div[class^='highlight'] pre {
 	font-size: 14pt;
-	line-height: 1.25;
+	line-height: 1.35;
+}
+.rst-content li {
+	margin-bottom: 0.5em;
 }
 .wy-nav-content {
    max-width: 1050px

conf.py

@@ -14,10 +14,9 @@
 
 import sys
 import os
+
 import sphinx_rtd_theme
-
 html_theme = "sphinx_rtd_theme"
-
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -262,5 +261,13 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
+html_context = {
+'display_github': True,
+'github_user': 'syncthing',
+'github_repo': 'docs',
+'github_version': 'master/',
+'source_suffix': '.rst',
+}
+
 def setup(app):
    app.add_stylesheet("syncthing.css")

dev/building.rst

@@ -1,3 +1,5 @@
+.. _building:
+
 Building Syncthing
 ==================
 
@@ -48,7 +50,7 @@ Building (Unix)
     # well what you're doing.
     $ mkdir -p ~/src/github.com/syncthing
     $ cd ~/src/github.com/syncthing
-    # Note that if you are building from a source code archive, you need to 
+    # Note that if you are building from a source code archive, you need to
     # rename the directory from syncthing-XX.YY.ZZ to syncthing
     $ git clone https://github.com/syncthing/syncthing
 
@@ -76,7 +78,7 @@ Building (Windows)
     # well what you're doing.
     > mkdir c:\src\github.com\syncthing
     > cd c:\src\github.com\syncthing
-    # Note that if you are building from a source code archive, you need to 
+    # Note that if you are building from a source code archive, you need to
     # rename the directory from syncthing-XX.YY.ZZ to syncthing
     > git clone https://github.com/syncthing/syncthing
 

dev/debugging.rst

@@ -1,3 +1,5 @@
+.. _debugging:
+
 Debugging Syncthing
 ===================
 

index.rst

@@ -1,49 +1,49 @@
-.. Syncthing documentation master file, created by
-   sphinx-quickstart on Thu May 28 08:33:11 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Syncthing's documentation!
 =====================================
 
-The main documentation for the site is organized into a couple sections:
+As a new user, the :ref:`getting started guide <getting-started>` is a good
+place to start, then perhaps moving on to :ref:`the FAQ <faq>`. If you run
+into trouble getting devices to connect to each other, the page about
+:ref:`firewall setup <firewall-setup>` explains the networking necessary to
+get it to work.
 
-* :ref:`intro-docs`
-* :ref:`user-docs`
-* :ref:`dev-docs`
+As a developer looking to get started with a contribution, see :ref:`how to build <building>`, :ref:`how to debug <debugging>` and the `contribution guidelines <https://github.com/syncthing/syncthing/blob/master/CONTRIBUTING.md>`_. This documentation site can be `edited here <https://github.com/syncthing/docs>`_.
 
-Contents:
+Contact
+-------
 
-.. _intro-docs:
+* To report bugs or request features, please use the `issue tracker <https://github.com/syncthing/syncthing/issues>`_. Before you do so, make sure you are running the `latest version <https://github.com/syncthing/syncthing/releases/latest>`_, and please do a quick search to see if the issue has already been reported.
+
+* To report security issues, please follow the instructions on the `Security page <https://syncthing.net/security.html>`_.
+
+* To get help and support, to discuss scenarios, or just connect with other users and developers you can head over to the `friendly forum <https://forum.syncthing.net/>`_.
+
+* For a more real time experience, there's also an IRC channel ``#syncthing`` on Freenode.
+
+* For other concerns you may reach out to members of the core team, currently `@calmh <https://github.com/calmh>`_, `@AudriusButkevicius <https://github.com/AudriusButkevicius>`_ and `@Zillode <https://github.com/Zillode>`_.
+
+The main documentation for the site is organized into a couple of sections. You can use the heading in the left sidebar to navigate the site.
 
 .. toctree::
    :caption: Introduction
    :maxdepth: 1
    :glob:
 
-   intro/*
-
-.. _user-docs:
+   intro/getting-started
+   intro/gui
 
 .. toctree::
    :caption: For Users
    :maxdepth: 1
    :glob:
 
+   users/faq
+   users/firewall
    users/*
 
-.. _dev-docs:
-
 .. toctree::
    :caption: For Developers
    :maxdepth: 1
    :glob:
 
    dev/*
-
-
-Indices and tables
-==================
-
-* :ref:`search`
-

intro/getting-started.rst

@@ -1,3 +1,5 @@
+.. _getting-started:
+
 Getting Started
 ===============
 
@@ -15,18 +17,16 @@ immediately obvious.
 Installing
 ----------
 
-We suggest you have a look to many of the `community contributions`_ which let
+We suggest you have a look to many of the :ref:`contributions` which let
 you pick a flavor of Syncthing that best fits your scenario. For example, if you
 are interested in a cross-platform GUI application you can check out
-`Syncthing-GTK`_. The community has also developed Windows, Android and `many
-more`_ specific flavors that help you run Syncthing on your devices. Currently
+`Syncthing-GTK`_. The community has also developed Windows, Android and many
+more specific flavors that help you run Syncthing on your devices. Currently
 all community flavors run the same Syncthing core underneath, so don't worry
 about changing your flavor at a later point in time. The remainder of this page
 will explain how to set up two devices with the core Syncthing flavor.
 
-.. _`community contributions`: http://docs.syncthing.net/users/contrib.html
 .. _`Syncthing-GTK`: https://github.com/syncthing/syncthing-gtk
-.. _`many more`: http://docs.syncthing.net/users/contrib.html
 
 Syncthing
 ~~~~~~~~~
@@ -111,12 +111,12 @@ need for a restart.
 
 Syncthing needs to be restarted for some configuration changes to take
 effect (such as sharing folders with new devices). When you click
-"Restart" Syncthing will first restart…
+"Restart" Syncthing will first restart:
 
 .. figure:: gs4.png
    :alt: gs4.png
 
-… then come back up and after a while (up to a minute) connect to the
+and then come back up and after a while (up to a minute) connect to the
 other device. Remember though that you need to do the above process on
 both devices, and only once you've done this on both devices will they
 be able to connect.
@@ -137,7 +137,6 @@ Good luck and have fun! There is more
 `documentation <http://docs.syncthing.net/>`__ and if you run into
 trouble feel free to post a question in the `support
 forum <http://forum.syncthing.net/category/support>`__. If you have
-problems getting this to connect, first take a look at `Firewalls and
-Port Forwards <http://docs.syncthing.net/users/firewalls.html>`__, then
+problems getting this to connect, first take a look at :ref:`firewall-setup`, then
 look at any error messages in the GUI or on the console and if necessary
-move on to `Debugging <http://docs.syncthing.net/dev/debugging.html>`__.
+move on to :ref:`debugging`.

intro/index.md

@@ -1,11 +0,0 @@
----
-title: Index
-nav: false
----
-
-{% assign pages = site.intro | sort: 'title' | sort: 'weight' %}
-{% for node in pages %}
-{% if node.title != null and node.nav == true %}
-<a class="sidebar-nav-item{% if page.url == node.url %} active{% endif %}" href="{{ site.baseurl }}{{ node.url }}">{{ node.title }}</a>
-{% endif %}
-{% endfor %}

users/contrib.rst

@@ -1,3 +1,5 @@
+.. _contributions:
+
 Community Contributions
 =======================
 

users/faq.rst

@@ -1,3 +1,5 @@
+.. _faq:
+
 FAQ
 ===
 

users/firewall.rst

@@ -1,5 +1,7 @@
-Firewalls
-=========
+.. _firewall-setup:
+
+Firewall Setup
+==============
 
 Port Forwards
 -------------