This is a documentation site for Synapse. Synapse is an open source software platform that data scientists use to carry out, track, and communicate their research in real time.
Synapse Docs is generated using Jekyll and uses redcarpet to render Markdown. Various page layouts can be found under the _layouts folder in the home directory. Most everything can be written using standard Markdown.
Internal development can be performed by branching from develop to your own feature branch, making changes, pushing the branch to this repository, and opening a pull request. Pull requests against the master branch require a review before merging.
Note: even if the build succeeds, it can take 15-30 minutes for content in master to be reflected on the live site. Don't panic. :)
To create a page using the article layout, start by specifying at the very beginning the title, layout, excerpt, and category in the YAML front matter. The title and excerpt will show up in the article's user guide thumbnail and the category tag will be used to sort the article into its corresponding user guide tab. If no category is specified, it will default into the "How-To" tab.
category options: intro, howto, governance, dream, inpractice
Note that the front matter needs to be enclosed between three dashed lines to work properly.
---
title: Name of page here
layout: article
excerpt: A blurb about this page that will show up as a description in the user guide.
category: intro
---
Article content should begin with a short summary describing what the page is about. Each header on the page will be rendered on the sidebar menu as well for easier navigation.
You can use Liquid tags to show a code example in multiple languages. Follow the format below for as many languages as you'd like, ensuring that the languages are in alphabetical order.
{% tabs %}
{% tab Command %}
{% highlight bash %}
some code here
{% endhighlight %}
{% endtab %}
{% tab Python %}
{% highlight python %}
more code here
{% endhighlight %}
{% endtab %}
{% tab R %}
{% highlight r %}
add code here
{% endhighlight %}
{% endtab %}
{% tab Web %}
Instructions for Web + screenshots
{% endtab %}
{% endtabs %}
There are four types of alert highlighting to inform users: note, tip, warning, and important. You can insert an alert by using any of the following code in a markdown file.
{% include note.html content="This is a note." %}
{% include tip.html content="This is a tip." %}
To include new paragraphs, just add the <br/> tag within the content, like this:
{% include warning.html content="This is a warning. `<br/>` This is the second line of the warning." %}
{% include important.html content="This is for an important message." %}
To add a table, use Liquid to call on the markdown-table css class. Then use the standard markdown table format.
{:.markdown-table}
| Header 1 | Header 2 |
| --- | --- |
| content | content |
| content | content |
Images can be inserted using either Markdown or HTML, it all depends on your preference. The examples below will display the same thing:
<img src="/assets/images/image1.jpg" alt="alt text">
To install bundler (mac, install brew first):
brew install ruby npm
gem install bundler
With Bundler:
bundle install
npm install
bundle exec jekyll serve
then navigate to localhost:4000
./bin/jekyll build
Solving common bugs while regenerating Connection refused error:
Source: .
Destination: ./_site
Incremental build: disabled. Enable with --incremental
Generating...
Conversion error: Jekyll::BrowserifyConverter encountered an error while converting '/js/all.js':
Connection refused - connect(2)
jekyll 3.1.2 | Error: Connection refused - connect(2)
When you get this error, run this command several times before regenerating again.
ulimit -n 10000
Distributed under the Eclipse Public License, the same as Clojure.