4d420aea18
This addresses https://github.com/openhab/openhab-docs/pull/355#issuecomment-283513476 Also updated a handful of binding docs resulting from `./update.sh`. @ThomDietrich, the very long list of Bindings in the menu show their duplicate labels as expected, but one way to improve that is to create a new layout, based on the “documentation” layout, perhaps called “addon”, that shows the metadata on the page (like badges if `install` or `since` metadata given, logo if given, “improve this document” button if `source` given). Then all you have to do to use the new layout is update `_config.yml` for those collections to which you wish to apply the new layout. With such a layout, readers’ puzzlement over the duplicate labels would be quickly dispelled. Would you consider adding a new custom “addon” layout? Should I? I don’t think adorning the binding menu items themselves with badges or parenthetical metadata would look good. Signed-off-by: John Cocula <john@cocula.com> |
||
|---|---|---|
| _actions | ||
| _bindings | ||
| _iconsets/classic | ||
| _includes | ||
| _io | ||
| _layouts | ||
| _persistence | ||
| _repos | ||
| _sample_code/osgi_codings_tasks/bundles | ||
| _sass | ||
| _uis | ||
| _voice | ||
| addons | ||
| administration | ||
| appendix | ||
| community | ||
| concepts | ||
| configuration | ||
| css | ||
| developers | ||
| features | ||
| font/material-design-icons | ||
| images | ||
| installation | ||
| js | ||
| tutorials | ||
| .editorconfig | ||
| .gitignore | ||
| .gitmodules | ||
| 404.md | ||
| CNAME | ||
| CONTRIBUTING.md | ||
| README.md | ||
| Vagrantfile | ||
| _config.yml | ||
| favicon.ico | ||
| imprint.md | ||
| index.html | ||
| introduction.md | ||
| overview.md | ||
| pom.xml | ||
| privacy.md | ||
| process_addons.groovy | ||
| redirect-test.md | ||
| search.html | ||
| update.sh | ||
README.md
Introduction
This repository contains the documentation for openHAB.
The result is available at http://docs.openhab.org/
Contributing to the Documentation
The documentation is a community effort, so everyone is welcome to suggest changes, add new sections and fix bugs. This is done exactly the same way as for the code repositories, simply through pull requests against this repo. Please read the contribution guidelines for details.
Prerequisites
Our documentation is built with Jekyll and served through Github Pages.
In order to run Jekyll locally, you also need Ruby being installed. Please see the Jekyll installation instructions for details.
An alternative for a local setup is a virtual machine provided by Vagrant.
Serving the Documentation locally
Once you have Jekyll installed and the repository checked out, simply run
jekyll serve
from within the repository root folder and point your browser to http://localhost:4000.
This will give you a preview of the documentation in the same way as it will appear on docs.openhab.org once your PR is merged.
Changes to the markdown files will automatically be taken into account as Jekyll re-generates the pages on the fly.
Alternative: Vagrant VM
You can also have a virtual machine serving a Jekyll and webserver instance for you, without changing your base system or being limited by it.
The virtual machine will run in the background, process your changes to the source and presenting the results on your hosts http://localhost:4000.
A Vagrant machine configured by a Vagrantfile file is provided for that purpose.
You need to have VirtualBox and Vagrant installed. After that, it's as easy as:
/path-to/openhab-docs$ vagrant up
Automatically Generated Parts
Please note that a few parts MUST NOT BE MANUALLY EDITED! These are copied from the source code repositories and some files are generated from them. These files/folders are:
_source/_data
_source/concepts
_source/addons/bindings
_source/addons/iconsets
_source/addons/io
_source/addons/uis
The generation/update of these files can be triggered through mvn clean package in the repo root.
Please note that this repository works with sub-modules, so if you want to run this Maven generation, you should check out the repository recursively:
git clone --recursive https://github.com/openhab/openhab-docs