From 91c581e678313aff8274aefac53245ab8d4193a7 Mon Sep 17 00:00:00 2001 From: Christopher Gervais Date: Fri, 3 Mar 2017 09:43:14 -0500 Subject: [PATCH] Add basic Mkdocs config and initial docs. --- docs/_css/term.css | 17 +++++++++++++++++ docs/documentation.md | 32 ++++++++++++++++++++++++++++++++ docs/features.md | 9 +++++++++ docs/index.md | 33 +++++++++++++++++++++++++++++++++ docs/install.md | 8 ++++++++ docs/scripts/install.sh | 10 ++++++++++ docs/scripts/serve.sh | 10 ++++++++++ mkdocs.yml | 14 ++++++++++++++ 8 files changed, 133 insertions(+) create mode 100644 docs/_css/term.css create mode 100644 docs/documentation.md create mode 100644 docs/features.md create mode 100644 docs/index.md create mode 100644 docs/install.md create mode 100755 docs/scripts/install.sh create mode 100755 docs/scripts/serve.sh create mode 100644 mkdocs.yml diff --git a/docs/_css/term.css b/docs/_css/term.css new file mode 100644 index 000000000..7d602db6b --- /dev/null +++ b/docs/_css/term.css @@ -0,0 +1,17 @@ +pre code.console { + background-color: black; + color: #808080; + padding: 1em; + border-radius: 5px; + font-size: 110%; + overflow: auto; +} + +span.hljs-built_in, +span.hljs-comment, +span.hljs-keyword, +span.hljs-variable { + color: #808080; + font-weight: normal; + font-style: normal; +} diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 000000000..344db6721 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,32 @@ +Documentation +============= + +The LibreTime documentation site is generated with [mkdocs](http://www.mkdocs.org/). To get started contributing to this project, fork it on Github. Then install mkdocs and clone this repo locally: + +```console +$ sudo brew install python # For OSX users +$ sudo aptitude install python-pip # For Debian/Ubuntu users +$ sudo pip install mkdocs +$ git clone https://github.com/libretime/libretime +$ cd libretime +$ git remote add sandbox https://github.com//libretime # URL for your fork +$ mkdocs build --clean +$ mkdocs serve +``` + +Your local LibreTime docs site should now be available for browsing: [http://localhost:8888/](http://localhost:8888/). + +When you find a typo, an error, unclear or missing explanations or instructions, open a new terminal and start editing. Your changes should be reflected automatically on the local server. Find the page you’d like to edit; everything is in the docs/ directory. Make your changes, commit and push them, and start a pull request: + +```console +$ git checkout -b fix_typo +$ vi docs/index.md # Add/edit/remove whatever you see fit. Be bold! +$ mkdocs build --clean; mkdocs serve # Go check your changes. We’ll wait... +$ git diff # Make sure there aren’t any unintended changes. +diff --git a/docs/index.md b/docs/index.md +... +$ git commit -am”Fixed typo.” # Useful commit message are a good habit. +$ git push sandbox fix_typo +``` + +Visit your fork on Github and start a PR. diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 000000000..3df32286b --- /dev/null +++ b/docs/features.md @@ -0,0 +1,9 @@ +Features +======== + +TBD + +Screenshots +----------- + +TBD diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..14badee97 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,33 @@ +Welcome to LibreTime +==================== + +LibreTime makes it easy to run your own online radio station. Check out some [features](features.md) and [screenshots](features.md#screenshots), then [install it](install.md) and start broadcasting! + +LibreTime is Free/Libre and Open Source Software (FLOSS). Among other things, this means that you have the freedom to: + +* Run it royalty-free for as long as you like. +* Read and alter the code that makes it work (or hire someone to do this for you!) +* Contribute documentation, bug-fixes, etc. so that everyone in the community benefits. + +LibreTime is a fork of AirTime due to stalled development of the FLOSS version. For background on this, see this [open letter to the Airtime community](https://gist.github.com/hairmare/8c03b69c9accc90cfe31fd7e77c3b07d). + + +Getting Started +--------------- + +The easiest way to check out LibreTime for yourself is to run a local instance in a virtual machine: + +1. Install Git, Vagrant and Virtualbox: +```console +$ sudo apt-get install git vagrant virtualbox +``` +2. Clone this repository locally: +```console +$ git clone https://github.com/libretime/libretime.git +``` +3. Launch the VM: +```console +$ cd libretime +$ vagrant up +``` + diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..d86404211 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,8 @@ +Installing LibreTime +==================== + +LibreTime should generally be installed on a dedicated host. By default, its installer will install and configure all its dependencies. + +```console +$ ./installer +``` diff --git a/docs/scripts/install.sh b/docs/scripts/install.sh new file mode 100755 index 000000000..d7fb756f3 --- /dev/null +++ b/docs/scripts/install.sh @@ -0,0 +1,10 @@ +#! /bin/sh + +echo "Updating Apt." +apt-get update > /dev/null +echo "Ensuring Pip is installed." +DEBIAN_FRONTEND=noninteractive apt-get install -y -qq python-pip > /dev/null +echo "Updating Pip." +pip install pip -q -q --upgrade > /dev/null +echo "Ensuring Mkdocs is installed." +pip install -q mkdocs > /dev/null diff --git a/docs/scripts/serve.sh b/docs/scripts/serve.sh new file mode 100755 index 000000000..2596ef316 --- /dev/null +++ b/docs/scripts/serve.sh @@ -0,0 +1,10 @@ +#! /bin/sh + +cd /vagrant +echo "Stopping any running Mkdocs servers." +pkill mkdocs +echo "Building Mkdocs documentation." +mkdocs build --clean -q > /dev/null +echo "Launching Mkdocs server." +mkdocs serve > /dev/null 2>&1 & +echo "Visit http://localhost:8888 to see the LibreTime documentation." diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..5d7ca526d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,14 @@ +site_name: LibreTime +theme: readthedocs + +dev_addr: '0.0.0.0:8888' +site_dir: '/tmp/aegir_docs/_site' + +extra_css: + - '_css/term.css' + +pages: + - 'Home': index.md + - 'Features': features.md + - 'Install': install.md + - 'Documentation': documentation.md