Update docs for rst on RTD

.gitignore

@@ -31,3 +31,5 @@ docs/_build/
 # stupid ds_store:
 .DS_Store
 
+# JetBrains
+.idea

README.md

@@ -1,142 +1,43 @@
-# Major Update as of Nov 23, 2018
-
-The old labstreaminglayer repository has moved to https://github.com/sccn/lsl_archived . 
-
-If you cloned/forked labstreaminglayer before the move, then you must redo this to get the latest source code. Please note that this repository uses submodules so you will have to do a recursive clone: `git clone --recursive https://github.com/sccn/labstreaminglayer.git`.
-
-This repository is a container for all labstreaminglayer-related repositories.
-The core library (liblsl) is hosted in the sccn organization.
-Language wrappers and apps are hosted in the https://github.com/labstreaminglayer organization.
-
-If you have any outstanding issues that need addressing then please comment on them in the lsl_archived repo. We will continue to monitor that repo and will transfer issues here as needed.
-If you were working on any changes against the old repo then you can make a pull request against lsl_archived and we will take care of applying it to the new repo.
-
 # Summary
 
 The **lab streaming layer** (LSL) is a system for the unified collection of measurement time series
 in research experiments that handles both the networking, time-synchronization, (near-) real-time
 access as well as optionally the centralized collection, viewing and disk recording of the data.
 
-The **LSL distribution** consists of:
-- The core transport library
-([liblsl](https://github.com/sccn/liblsl/)) and its language interfaces
-  ([C](https://github.com/sccn/liblsl/),
-  [C++](https://github.com/sccn/liblsl/),
-  [Python](https://github.com/labstreaminglayer/liblsl-Python/),
-  [Java](https://github.com/labstreaminglayer/liblsl-Java/),
-  [C#](https://github.com/labstreaminglayer/liblsl-Csharp/),
-  [MATLAB](https://github.com/labstreaminglayer/liblsl-Matlab/)).
-  The library is general-purpose and cross-platform (Win/Linux/MacOS/
-  [Android](https://github.com/labstreaminglayer/liblsl-Android/)/iOS, x86/amd64/arm)
-  and forms the heart of the project.
-- A suite of tools built on top of the library, including a
-  [recording program](https://github.com/labstreaminglayer/App-LabRecorder),
-  [file importers](https://github.com/sccn/xdf),
-  and apps that make data from a range of
-  [acquisition hardware](https://github.com/sccn/labstreaminglayer/wiki/SupportedDevices)
-  available on the lab network (for example audio, EEG, or motion capture).
-
-There is an intro lecture/demo on LSL here: [http://www.youtube.com/watch?v=Y1at7yrcFW0](http://www.youtube.com/watch?v=Y1at7yrcFW0)
-(part of an online course on EEG-based brain-computer interfaces).
-
-You may also wish to subscribe to the [LSL mailing list](https://mailman.ucsd.edu/mailman/listinfo/lsl-l)
-
-This is only a repository containing submodules for all projects. Depending on your needs, you should
-either download ready-to-use binary packages or clone just the repositories you need (see
-[liblsl](https://github.com/labstreaminglayer/labstreaminglayer/tree/master/LSL) for an overview).
-
-## Download Binary Releases
-
-You can find *old* releases on our FTP site: ftp://sccn.ucsd.edu/pub/software/LSL/.
-
-These releases are out of date. We are working toward an automated build and deployment system
-but it is not ready yet.
-
-## Streaming Layer API
-
-The liblsl library provides the following **abstractions** for use by client programs:
-
-- **Stream Outlets**: for making time series data streams available on the lab network.
-  The data is pushed sample-by-sample or chunk-by-chunk into the outlet, and can consist of
-  single- or multichannel data, regular or irregular sampling rate, with uniform value types
-  (integers, floats, doubles, strings). Streams can have arbitrary XML meta-data (akin to a
-  file header). By creating an outlet the stream is made visible to a collection of computers
-  (defined by the network settings/layout) where one can subscribe to it by creating an inlet.
-
-- **Resolve functions**: these allow to resolve streams that are present on the lab network
-  according to content-based queries (for example, by name, content-type, or queries on the
-  meta-data). The service discovery features do not depend on external services such as zeroconf
-  and are meant to drastically simplify the data collection network setup.
-
-- **Stream Inlets**: for receiving time series data from a connected outlet.
-  Allows to retrieve samples from the provider (in-order, with reliable transmission,
-  optional type conversion and optional failure recovery). Besides the samples, the meta-data
-  can be obtained (as XML blob or alternatively through a small built-in DOM interface).
-
-- **Built-in clock**: Allows to time-stamp the transmitted samples so that they can be mutually
-  synchronized. See Time Synchronization.
-
-## Reliability
-
-The following reliability features are implemented by the library (transparently):
-- Transport inherits the reliability of TCP, is message-oriented (partitioned into
-  samples) and type safe.
-
-- The library provides automatic failure recovery from application or computer crashes to minimize
-  data loss (optional); this makes it possible to replace a computer in the middle of a recording
-  without having to restart the data collection.
-
-- Data is buffered both at the sender and receiver side (with configurable and arbitrarily large
-  buffers) to tolerate intermittent network failures.
-
-- Transmission is type safe, and supports type conversions as necessary.
-
-## Time Synchronization
-
-The lab streaming layer comes with a built-in synchronized time facility for all recorded data which
-is designed to achieve sub-millisecond accuracy on a local network of computers.
-This facility serves to provide out-of-the-box support for synchronized data collection but does not
-preclude the use of user-supplied alternative timestamps, for example from commercial timing
-middleware or high-quality clocks.
-
-The built-in time synchronization is designed after the widely deployed Network Time Protocol (NTP)
-and implemented in the LSL library.
-
-This feature is explained in more detail in the
-[TimeSynchronization](https://github.com/sccn/labstreaminglayer/wiki/TimeSynchronization.wiki) section.
-
-## File Format
-
-The transport API itself does not endorse or provide a particular file format, but the provided recording
-program (`LabRecorder`) <!--and Python/C++ library (`RecorderLib`)--> records into the XDF file format
-([Extensible Data Format](https://github.com/sccn/xdf)). XDF was designed concurrently with
-the lab streaming layer and supports the full feature set of LSL (including multi-stream container
-files, per-stream arbitrarily large XML headers, all sample formats as well as time-synchronization
-information).
-
-## Developer Information
+# Quick Start
 
-Please see the separate [build documentation](doc/BUILD.md).
+The most common way to use LSL is to use one or more applications with integrated LSL functionality.
 
-The distribution includes a range of code examples in C, C++, Python, MATLAB, Java, and C# including
-some very simple sender and receiver programs, as well as some fairly extensive demo apps.
+* Take a look at the list of [supported devices](https://github.com/sccn/labstreaminglayer/wiki/SupportedDevices)
+and follow the instructions to start streaming data from your device.
+If your device is not in the list then see the "Getting Help" section below.
+* Download [LabRecorder](https://github.com/labstreaminglayer/App-LabRecorder) from its
+[release page](https://github.com/labstreaminglayer/App-LabRecorder/releases). (Note that LabRecorder
+saves data to [Extensible Data Format (xdf)](https://github.com/sccn/xdf) which has its own set of
+tools for loading data after finishing recording.)
+* Use LSL from your scientific computing environment. LSL has many language interfaces,
+including Python and Matlab. Python users need only `pip install pylsl` then try some of the
+[provided examples](https://github.com/labstreaminglayer/liblsl-Python/tree/master/pylsl/examples).
+The [Matlab interface](https://github.com/labstreaminglayer/liblsl-Matlab/) is also popular but
+requires a little more work to get started; please see its README for more info.
 
-See [ExampleCode](https://github.com/labstreaminglayer/App-Examples/) for a broader
-overview of example programs, API documentation link, and general programming tips, tricks, and
-frequently asked questions.
+If you are not sure what you are looking for then try browsing through the code which has submodule links to different
+repositories for tools and devices (Apps) and language interfaces (LSL). When you land in a new repository then be sure
+to read its README and look at its Releases page.
 
-## How to get support
+## Getting Help
 
 If you are having trouble with LSL, there are few things you can do to get help.
-First, look to the [Wiki](https://github.com/sccn/labstreaminglayer/wiki), especially the [frequently asked questions](https://github.com/sccn/labstreaminglayer/wiki/Frequently-Asked-Questions).
-Second, search the issues list, including closed issues, in this repository and in the archived repository [here](https://github.com/sccn/lsl_archived).
-If you don't find what you are looking for, then you can create a new issue. Try to include as much
-information as possible about your device (if applicable), your computing environment (operating
-system, processor achitecture), what you have tested so far, and also provide logs or other error
-messages if available. If you create a new issue then please be responsive to follow-up questions and be sure to close it once the issue is solved.
 
-You can also try joining the LabStreamingLayer `#users` channel on Slack. [Invite Link](https://join.slack.com/t/labstreaminglayer/shared_invite/enQtMzA2NjEwNDk0NjA5LTcyYWI4ZDk5OTY5MGI2YWYxNmViNjhkYWRhZTkwYWM0ODY0Y2M0YzdlZDRkZTg1OTUwZDU2M2UwNDgwYzUzNDg).
+* [Read the docs](https://labstreaminglayer.readthedocs.io/)
+* Search GitHub issues in this repository, in the old [archived repository](https://github.com/sccn/lsl_archived),
+  and in the submodule for your App or language interface of interest.
+* Create a new GitHub issue. Please use the repository specific to the item you are having difficulty with.
+  e.g. if you are having trouble with LabRecorder then open a new issue in its repository.
+  If you don't know which repository is best then you can use the parent sccn/labstreaminglayer repository.
+* Join the LabStreamingLayer `#users` channel on Slack. [Invite Link](https://join.slack.com/t/labstreaminglayer/shared_invite/enQtMzA2NjEwNDk0NjA5LTcyYWI4ZDk5OTY5MGI2YWYxNmViNjhkYWRhZTkwYWM0ODY0Y2M0YzdlZDRkZTg1OTUwZDU2M2UwNDgwYzUzNDg).
 Someone there may be able to get to the bottom of your problem through conversation.
+* You may also wish to subscribe to the [LSL mailing list](https://mailman.ucsd.edu/mailman/listinfo/lsl-l)
 
 ## Acknowledgements
 

docs/README.md

@@ -0,0 +1,9 @@
+This folder contains the documentation for LabStreamingLayer.
+Please find the compiled and rendered documentation on Read The Docs:
+https://labstreaminglayer.readthedocs.io
+
+For offline use:
+* You can find information about LSL, how to use LSL, troubleshooting,
+  device support etc in the `info` folder.
+* You can find the developer documentation for configuring and building
+  existing applications or your own application in the `dev` folder.

docs/conf.py

@@ -48,5 +48,4 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-master_doc = 'index' # for Sphinx < 2.0
-
+master_doc = 'index'  # for Sphinx < 2.0

docs/dev/dev_guide.rst

@@ -0,0 +1,8 @@
+Developer's Guide
+=================
+
+Add introductory text here.
+
+The distribution includes a range of code examples in C, C++, Python, MATLAB, Java, and C# including some very simple sender and receiver programs, as well as some fairly extensive demo apps.
+
+See `ExampleCode <https://github.com/labstreaminglayer/App-Examples/>`__ for a broader overview of example programs, API documentation link, and general programming tips, tricks, and frequently asked questions.

docs/index.rst

@@ -3,18 +3,20 @@ Welcome to Labstreaminglayer's documentation!
 
 .. toctree::
    :maxdepth: 1
-   :caption: User's guide
+   :caption: User's Guide
 
-   usersguide
+   info/intro
+   info/user_guide
+   info/supported_devices.rst
 
 .. toctree::
    :maxdepth: 1
-   :caption: Developer's guide
+   :caption: Developer's Guide
 
-   devguide
+   dev/dev_guide
    dev/build
-   dev/buildenv
-   dev/appdev
+   dev/build_env
+   dev/app_dev
    dev/repository
 
 

docs/info/intro.rst

@@ -0,0 +1,68 @@
+Introduction
+############
+
+What is LSL?
+************
+
+The **LSL distribution** consists of the core library and a suite of tools built on top of the library.
+
+The core transport library is `liblsl <https://github.com/labstreaminglayer/liblsl/>`__ and its language interfaces (`C <https://github.com/sccn/liblsl/>`__,
+  `C++ <https://github.com/sccn/liblsl/>`__, `Python <https://github.com/labstreaminglayer/liblsl-Python/>`__, `Java <https://github.com/labstreaminglayer/liblsl-Java/>`__, `C# <https://github.com/labstreaminglayer/liblsl-Csharp/>`__, `MATLAB <https://github.com/labstreaminglayer/liblsl-Matlab/>`__).
+  The library is general-purpose and cross-platform (OS Support: Win / Linux / MacOS / `Android <https://github.com/labstreaminglayer/liblsl-Android/>`__ / iOS;
+  Architecture Support: x86 / amd64 / arm).
+
+The suite of tools includes a `recording program <https://github.com/labstreaminglayer/App-LabRecorder>`__, `file importers <https://github.com/sccn/xdf>`__, and apps that make data from a range of `acquisition hardware <https://github.com/sccn/labstreaminglayer/wiki/SupportedDevices>`__ available on the lab network (for example audio, EEG, or motion capture).
+
+There is an intro lecture/demo on LSL here: http://www.youtube.com/watch?v=Y1at7yrcFW0 (part of an online course on EEG-based brain-computer interfaces).
+
+Streaming Layer API
+===================
+
+The liblsl library provides the following **abstractions** for use by client programs:
+
+- **Stream Outlets**: for making time series data streams available on the lab network. The data is pushed sample-by-sample or chunk-by-chunk into the outlet, and can consist of single- or multichannel data, regular or irregular sampling rate, with uniform value types (integers, floats, doubles, strings). Streams can have arbitrary XML meta-data (akin to a file header). By creating an outlet the stream is made visible to a collection of computers (defined by the network settings/layout) where one can subscribe to it by creating an inlet.
+- **Resolve functions**: these allow to resolve streams that are present on the lab network according to content-based queries (for example, by name, content-type, or queries on the meta-data). The service discovery features do not depend on external services such as zeroconf and are meant to drastically simplify the data collection network setup.
+- **Stream Inlets**: for receiving time series data from a connected outlet. Allows to retrieve samples from the provider (in-order, with reliable transmission, optional type conversion and optional failure recovery). Besides the samples, the meta-data can be obtained (as XML blob or alternatively through a small built-in DOM interface).
+- **Built-in clock**: Allows to time-stamp the transmitted samples so that they can be mutually synchronized. See Time Synchronization.
+
+Reliability
+===========
+
+The following reliability features are implemented by the library (transparently):
+
+- Transport inherits the reliability of TCP, is message-oriented (partitioned into samples) and type safe.
+- The library provides automatic failure recovery from application or computer crashes to minimize data loss (optional); this makes it possible to replace a computer in the middle of a recording without having to restart the data collection.
+- Data is buffered both at the sender and receiver side (with configurable and arbitrarily large buffers) to tolerate intermittent network failures.
+- Transmission is type safe, and supports type conversions as necessary.
+
+Time Synchronization
+====================
+
+The lab streaming layer comes with a built-in synchronized time facility for all recorded data which is designed to achieve sub-millisecond accuracy on a local network of computers. This facility serves to provide out-of-the-box support for synchronized data collection but does not preclude the use of user-supplied alternative timestamps, for example from commercial timing middleware or high-quality clocks.
+
+The built-in time synchronization is designed after the widely deployed Network Time Protocol (NTP) and implemented in the LSL library.
+
+This feature is explained in more detail in the `TimeSynchronization <https://github.com/sccn/labstreaminglayer/wiki/TimeSynchronization.wiki>`__ section.
+
+File Format
+===========
+
+The transport API itself does not endorse or provide a particular file format, but the provided recording program (``LabRecorder``) records into the XDF file format (`Extensible Data Format <https://github.com/sccn/xdf>`__). XDF was designed concurrently with the lab streaming layer and supports the full feature set of LSL (including multi-stream container files, per-stream arbitrarily large XML headers, all sample formats as well as time-synchronization information).
+
+Developer Information
+=====================
+
+Please see the separate [build documentation](doc/BUILD.md).
+
+Clock synchronization
+---------------------
+
+Here we talk about important functions like the local clock
+(:func:`lsl_local_clock`), a function to query a time offset
+(:func:`lsl_time_correction_ex`) and a function to get the library version used
+by the loaded library (:func:`lsl_library_version`).
+
+Creating outlets
+----------------
+
+The main outlet class is :class:`lsl::stream_outlet`.