diff --git a/README.md b/README.md new file mode 100644 index 000000000..1316a5e33 --- /dev/null +++ b/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/). diff --git a/_static/syncthing.css b/_static/syncthing.css index 9ef978051..a4b07c265 100644 --- a/_static/syncthing.css +++ b/_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 diff --git a/conf.py b/conf.py index a31446f23..d32d68f13 100644 --- a/conf.py +++ b/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") diff --git a/dev/building.rst b/dev/building.rst index bfdd3fa59..8f7a3968d 100644 --- a/dev/building.rst +++ b/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 diff --git a/dev/debugging.rst b/dev/debugging.rst index 671aaeb7f..af8bca95e 100644 --- a/dev/debugging.rst +++ b/dev/debugging.rst @@ -1,3 +1,5 @@ +.. _debugging: + Debugging Syncthing =================== diff --git a/index.rst b/index.rst index ef4c93e0b..f0f5810ae 100644 --- a/index.rst +++ b/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 ` is a good +place to start, then perhaps moving on to :ref:`the FAQ `. If you run +into trouble getting devices to connect to each other, the page about +:ref:`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 `, :ref:`how to debug ` and the `contribution guidelines `_. This documentation site can be `edited here `_. -Contents: +Contact +------- -.. _intro-docs: +* To report bugs or request features, please use the `issue tracker `_. Before you do so, make sure you are running the `latest version `_, 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 `_. + +* To get help and support, to discuss scenarios, or just connect with other users and developers you can head over to the `friendly forum `_. + +* 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 `_, `@AudriusButkevicius `_ and `@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` - diff --git a/intro/getting-started.rst b/intro/getting-started.rst index 14304934d..22ef6feba 100644 --- a/intro/getting-started.rst +++ b/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 `__ and if you run into trouble feel free to post a question in the `support forum `__. If you have -problems getting this to connect, first take a look at `Firewalls and -Port Forwards `__, 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 `__. +move on to :ref:`debugging`. diff --git a/intro/index.md b/intro/index.md deleted file mode 100644 index f76bfdb50..000000000 --- a/intro/index.md +++ /dev/null @@ -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 %} -{{ node.title }} -{% endif %} -{% endfor %} diff --git a/users/contrib.rst b/users/contrib.rst index 1e150320e..d86ac635d 100644 --- a/users/contrib.rst +++ b/users/contrib.rst @@ -1,3 +1,5 @@ +.. _contributions: + Community Contributions ======================= diff --git a/users/faq.rst b/users/faq.rst index aaeeffec5..4a1ab220a 100644 --- a/users/faq.rst +++ b/users/faq.rst @@ -1,3 +1,5 @@ +.. _faq: + FAQ === diff --git a/users/firewalls.rst b/users/firewall.rst similarity index 97% rename from users/firewalls.rst rename to users/firewall.rst index 2fbbaa11c..a3caaf5bf 100644 --- a/users/firewalls.rst +++ b/users/firewall.rst @@ -1,5 +1,7 @@ -Firewalls -========= +.. _firewall-setup: + +Firewall Setup +============== Port Forwards -------------