From 91c581e678313aff8274aefac53245ab8d4193a7 Mon Sep 17 00:00:00 2001 From: Christopher Gervais Date: Fri, 3 Mar 2017 09:43:14 -0500 Subject: [PATCH 1/6] 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 From 203716ea508de2205cf9d938e3fb5cad99a8ac40 Mon Sep 17 00:00:00 2001 From: Christopher Gervais Date: Fri, 3 Mar 2017 13:27:51 -0500 Subject: [PATCH 2/6] Clarify some docs and improve code highlighting. --- docs/_css/term.css | 16 +++++++--------- docs/documentation.md | 36 ++++++++++++++++-------------------- docs/index.md | 20 ++++++-------------- docs/install.md | 9 +++++---- mkdocs.yml | 4 ++++ 5 files changed, 38 insertions(+), 47 deletions(-) diff --git a/docs/_css/term.css b/docs/_css/term.css index 7d602db6b..23802723a 100644 --- a/docs/_css/term.css +++ b/docs/_css/term.css @@ -1,17 +1,15 @@ -pre code.console { +pre.codehilite > code, +div.codehilite > pre { background-color: black; color: #808080; padding: 1em; - border-radius: 5px; + border-radius: 3px; font-size: 110%; + font-weight: bold; overflow: auto; } -span.hljs-built_in, -span.hljs-comment, -span.hljs-keyword, -span.hljs-variable { - color: #808080; - font-weight: normal; - font-style: normal; +pre.codehilite > code.language-console > span, +div.codehilite > pre > span[style*="color: #AA22FF"] { + color: #808080 !important; } diff --git a/docs/documentation.md b/docs/documentation.md index 344db6721..3145b07f8 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -3,30 +3,26 @@ 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 -``` + :::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 -``` + :::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. + $ 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/index.md b/docs/index.md index 14badee97..dee947f61 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,19 +15,11 @@ LibreTime is a fork of AirTime due to stalled development of the FLOSS version. Getting Started --------------- -The easiest way to check out LibreTime for yourself is to run a local instance in a virtual machine: +The easiest way to check out LibreTime for yourself is to run a local instance in a virtual machine. Assuming you already have Git, Vagrant and Virtualbox installed, just run: -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 -``` + :::console + $ git clone https://github.com/libretime/libretime.git + $ cd libretime + $ vagrant up +Of course, this setup isn't appropriate for production use. For that, check out our [installation instructions](install.md). diff --git a/docs/install.md b/docs/install.md index d86404211..d26a1dfc7 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,8 +1,9 @@ Installing LibreTime ==================== -LibreTime should generally be installed on a dedicated host. By default, its installer will install and configure all its dependencies. +LibreTime should generally be installed on a dedicated host. By default, its installer will install and configure all its dependencies. At the moment, the installer works best on Ubuntu Trusty. -```console -$ ./installer -``` + :::console + $ ./install + +Plans are in the works for ```.deb``` and ```.rpm``` packages, as well as Docker and AWS images. diff --git a/mkdocs.yml b/mkdocs.yml index 5d7ca526d..ab3b28ee8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,6 +3,10 @@ theme: readthedocs dev_addr: '0.0.0.0:8888' site_dir: '/tmp/aegir_docs/_site' +markdown_extensions: +- codehilite: + noclasses: True + pygments_style: emacs extra_css: - '_css/term.css' From 1fddc4186851ed9daa409a7cc87baeef548c3acb Mon Sep 17 00:00:00 2001 From: Lucas Bickel Date: Sat, 4 Mar 2017 14:47:23 +0100 Subject: [PATCH 3/6] Configure .travis.yml for mkdocs --- .travis.yml | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index f8eb9d97f..0702b2db5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -11,6 +11,7 @@ env: - LIBRETIME_LOG_DIR=/tmp/log/libretime install: - composer install +- pip install --user mkdocs before_script: - psql -c 'CREATE DATABASE libretime;' -U postgres - psql -c "CREATE USER libretime WITH PASSWORD 'libretime';" -U postgres @@ -18,4 +19,16 @@ before_script: - psql -c 'ALTER USER libretime CREATEDB;' -U postgres - mkdir -p /tmp/log/libretime script: -- cd airtime_mvc/tests && ../../vendor/bin/phpunit +- pushd airtime_mvc/tests && ../../vendor/bin/phpunit && popd +- mkdocs build --clean -q > /dev/null +deploy: + provider: pages + skip_cleanup: true + local_dir: build/docs + github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard + target_branch: master + project_name: LibreTime/LibreTime.github.io + fqdn: libretime.org + name: R. LibreTime DocBot + on: + branch: master From fba9a132144d0fbcc70c8109019cd89abf929d53 Mon Sep 17 00:00:00 2001 From: Lucas Bickel Date: Sat, 4 Mar 2017 15:17:26 +0100 Subject: [PATCH 4/6] Add testing.md to docs --- docs/{TESTING.md => testing.md} | 0 mkdocs.yml | 4 +++- 2 files changed, 3 insertions(+), 1 deletion(-) rename docs/{TESTING.md => testing.md} (100%) diff --git a/docs/TESTING.md b/docs/testing.md similarity index 100% rename from docs/TESTING.md rename to docs/testing.md diff --git a/mkdocs.yml b/mkdocs.yml index ab3b28ee8..e90ca073f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,4 +15,6 @@ pages: - 'Home': index.md - 'Features': features.md - 'Install': install.md - - 'Documentation': documentation.md + - 'Development': + - 'Testing': testing.md + - 'Documentation': documentation.md From 8cc262ae1181695d27f8f71843fd545064626fc6 Mon Sep 17 00:00:00 2001 From: Lucas Bickel Date: Sat, 4 Mar 2017 15:27:21 +0100 Subject: [PATCH 5/6] Remove background-color completely We can revisit this but I want to merge this ASAP since it's just too nice to wait. --- docs/_css/term.css | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/_css/term.css b/docs/_css/term.css index 23802723a..3510c5ff7 100644 --- a/docs/_css/term.css +++ b/docs/_css/term.css @@ -1,6 +1,5 @@ pre.codehilite > code, div.codehilite > pre { - background-color: black; color: #808080; padding: 1em; border-radius: 3px; From fba5ce1ce50d0419b4dda0f152fd00abaccdb9d1 Mon Sep 17 00:00:00 2001 From: Lucas Bickel Date: Sat, 4 Mar 2017 15:30:05 +0100 Subject: [PATCH 6/6] Make examples copy/paste friendly --- docs/documentation.md | 32 ++++++++++++++++---------------- docs/index.md | 8 ++++---- docs/install.md | 4 ++-- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/documentation.md b/docs/documentation.md index 3145b07f8..a588dfdd2 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -3,26 +3,26 @@ 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 + :::bash + 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. - $ git commit -am”Fixed typo.” # Useful commit message are a good habit. - $ git push sandbox fix_typo + :::bash + 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. + 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/index.md b/docs/index.md index dee947f61..6dfb154c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,9 +17,9 @@ Getting Started The easiest way to check out LibreTime for yourself is to run a local instance in a virtual machine. Assuming you already have Git, Vagrant and Virtualbox installed, just run: - :::console - $ git clone https://github.com/libretime/libretime.git - $ cd libretime - $ vagrant up + :::bash + git clone https://github.com/libretime/libretime.git + cd libretime + vagrant up Of course, this setup isn't appropriate for production use. For that, check out our [installation instructions](install.md). diff --git a/docs/install.md b/docs/install.md index d26a1dfc7..385237ff5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -3,7 +3,7 @@ Installing LibreTime LibreTime should generally be installed on a dedicated host. By default, its installer will install and configure all its dependencies. At the moment, the installer works best on Ubuntu Trusty. - :::console - $ ./install + :::bash + ./install Plans are in the works for ```.deb``` and ```.rpm``` packages, as well as Docker and AWS images.