Skip to content

Commit 9f42527

Browse files
ExcodiburExcodibur
Excodibur
authored and
Excodibur
committed
chore: release v0.0.1
Initial (beta) release Created documentation
1 parent f88ac3f commit 9f42527

File tree

15 files changed

+3482
-1875
lines changed

15 files changed

+3482
-1875
lines changed

‎.github/workflows/publish-docs.yml‎

Lines changed: 77 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,77 @@
1-
# This is a basic workflow to help you get started with Actions
2-
3-
name: Publish Documentation
4-
5-
# Controls when the action will run.
6-
on:
7-
# Triggers the workflow on push or pull request events but only for the master branch
8-
push:
9-
paths:
10-
- 'docs/**.adoc'
11-
- '!docs/release-documentation.adoc'
12-
13-
# Allows you to run this workflow manually from the Actions tab
14-
workflow_dispatch:
15-
16-
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
17-
jobs:
18-
# This workflow contains a single job called "build"
19-
doc_build:
20-
# The type of runner that the job will run on
21-
runs-on: ubuntu-latest
22-
23-
# Steps represent a sequence of tasks that will be executed as part of the job
24-
steps:
25-
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
26-
- uses: actions/checkout@v2
27-
28-
- name: Prepare tag
29-
id: prepare_tag
30-
if: startsWith(github.ref, 'refs/tags/')
31-
run: |
32-
TAG_NAME="${GITHUB_REF##refs/tags/}"
33-
echo "::set-output name=tag_name::${TAG_NAME}"
34-
echo "::set-output name=deploy_tag_name::doc-${TAG_NAME}"
35-
36-
# Build HTML Asciidoc
37-
- name: Build Asciidoc
38-
id: adocbuild
39-
uses: avattathil/asciidoctor-action@master
40-
with:
41-
program: "asciidoctor -D doc --backend=html5 -o index.html doc/index.adoc"
42-
43-
- name: CHECK index.html
44-
run: cat doc/index.html
45-
46-
# Runs a single command using the runners shell
47-
- name: Deploy documentation to GH Pages
48-
uses: peaceiris/actions-gh-pages@v3
49-
with:
50-
github_token: ${{ secrets.GITHUB_TOKEN }}
51-
publish_dir: ./doc
52-
exclude_assets: '**.adoc,*/**.adoc,*/**.sh'
53-
destination_dir: ${{ steps.prepare_tag.outputs.deploy_tag_name }}
54-
tag_name: ${{ steps.prepare_tag.outputs.deploy_tag_name }}
55-
tag_message: 'Deployment ${{ steps.prepare_tag.outputs.tag_name }}'
1+
# This is a basic workflow to help you get started with Actions
2+
3+
name: Publish Documentation
4+
5+
# Controls when the action will run.
6+
on:
7+
# Triggers the workflow on push or pull request events but only for the master branch
8+
push:
9+
#paths:
10+
# - 'docs/**.adoc'
11+
# - '!docs/release-documentation.adoc'
12+
branches:
13+
- "master"
14+
tags:
15+
# normal versions
16+
- "v[0-9]+.[0-9]+.[0-9]+"
17+
# pre-releases
18+
- "v[0-9]+.[0-9]+.[0-9]+-**"
19+
20+
# Allows you to run this workflow manually from the Actions tab
21+
workflow_dispatch:
22+
23+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
24+
jobs:
25+
# This workflow contains a single job called "build"
26+
doc_build:
27+
# The type of runner that the job will run on
28+
runs-on: ubuntu-latest
29+
30+
# Steps represent a sequence of tasks that will be executed as part of the job
31+
steps:
32+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
33+
- uses: actions/checkout@v2
34+
35+
# TODO: Check if tag is latest and create symlink to release
36+
- name: Prepare tag
37+
id: prepare_tag
38+
if: startsWith(github.ref, 'refs/tags/')
39+
run: |
40+
TAG_NAME="${GITHUB_REF##refs/tags/}"
41+
if [ "$TAG_NAME" = $(git describe --tags --abbrev=0) ]; then
42+
echo "::set-output name=is_latest::true"
43+
if [ -z $TAG_NAME ]; then
44+
TAG_NAME=dev
45+
echo "::set-output name=tag_name::${TAG_NAME}"
46+
echo "::set-output name=deploy_tag_name::doc-${TAG_NAME}"
47+
48+
# Build HTML Asciidoc
49+
- name: Build Asciidoc
50+
id: adocbuild
51+
uses: avattathil/asciidoctor-action@master
52+
with:
53+
program: "asciidoctor -D doc --backend=html5 -o index.html doc/index.adoc"
54+
55+
#- name: CHECK index.html
56+
# run: cat doc/index.html
57+
58+
# Runs a single command using the runners shell
59+
- name: Deploy documentation to GH Pages
60+
uses: peaceiris/actions-gh-pages@v3
61+
with:
62+
github_token: ${{ secrets.GITHUB_TOKEN }}
63+
publish_dir: ./doc
64+
exclude_assets: '**.adoc,*/**.adoc,*/**.sh'
65+
keep_files: true
66+
destination_dir: ${{ steps.prepare_tag.outputs.deploy_tag_name }}
67+
tag_name: ${{ steps.prepare_tag.outputs.deploy_tag_name }}
68+
tag_message: 'Deployment ${{ steps.prepare_tag.outputs.tag_name }}'
69+
70+
# Change latest link in case there is a new documentation available
71+
- name: Update latest symlink
72+
if: ${{ steps.prepare_tag.outputs.is_latest}}
73+
run: |
74+
echo "tag is latest. need to update latest-symlink in gh-pages branch"
75+
76+
77+

‎.github/workflows/test-and-release.yml‎

Lines changed: 53 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -39,62 +39,57 @@ jobs:
3939
- name: Test package files
4040
run: npm run test:package
4141

42+
# Deploys the final package to NPM
43+
deploy:
44+
needs: [check-and-lint]
4245

43-
# TODO: To enable automatic npm releases, create a token on npmjs.org
44-
# Enter this token as a GitHub secret (with name NPM_TOKEN) in the repository options
45-
# Then uncomment the following block:
46-
47-
# # Deploys the final package to NPM
48-
# deploy:
49-
# needs: [check-and-lint]
50-
#
51-
# # Trigger this step only when a commit on master is tagged with a version number
52-
# if: |
53-
# contains(github.event.head_commit.message, '[skip ci]') == false &&
54-
# github.event_name == 'push' &&
55-
# github.event.base_ref == 'refs/heads/master' &&
56-
# startsWith(github.ref, 'refs/tags/v')
57-
#
58-
# runs-on: ubuntu-latest
59-
# strategy:
60-
# matrix:
61-
# node-version: [14.x]
62-
#
63-
# steps:
64-
# - name: Checkout code
65-
# uses: actions/checkout@v2
66-
#
67-
# - name: Use Node.js ${{ matrix.node-version }}
68-
# uses: actions/setup-node@v1
69-
# with:
70-
# node-version: ${{ matrix.node-version }}
71-
#
72-
# - name: Extract the version and commit body from the tag
73-
# # The body may be multiline, therefore newlines and % need to be escaped
74-
# run: |
75-
# VERSION="${{ github.ref }}"
76-
# VERSION=${VERSION##*/v}
77-
# echo "::set-env name=VERSION::$VERSION"
78-
# BODY=$(git show -s --format=%b)
79-
# BODY="${BODY//'%'/'%25'}"
80-
# BODY="${BODY//$'\n'/'%0A'}"
81-
# BODY="${BODY//$'\r'/'%0D'}"
82-
# echo "::set-env name=BODY::$BODY"
83-
#
84-
# - name: Publish package to npm
85-
# run: |
86-
# npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
87-
# npm whoami
88-
# npm publish
89-
#
90-
# - name: Create Github Release
91-
# uses: actions/create-release@v1
92-
# env:
93-
# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
94-
# with:
95-
# tag_name: ${{ github.ref }}
96-
# release_name: Release v${{ env.VERSION }}
97-
# draft: false
98-
# # Prerelease versions create prereleases on Github
99-
# prerelease: ${{ contains(env.VERSION, '-') }}
100-
# body: ${{ env.BODY }}
46+
# Trigger this step only when a commit on master is tagged with a version number
47+
if: |
48+
contains(github.event.head_commit.message, '[skip ci]') == false &&
49+
github.event_name == 'push' &&
50+
github.event.base_ref == 'refs/heads/master' &&
51+
startsWith(github.ref, 'refs/tags/v')
52+
53+
runs-on: ubuntu-latest
54+
strategy:
55+
matrix:
56+
node-version: [14.x]
57+
58+
steps:
59+
- name: Checkout code
60+
uses: actions/checkout@v2
61+
62+
- name: Use Node.js ${{ matrix.node-version }}
63+
uses: actions/setup-node@v1
64+
with:
65+
node-version: ${{ matrix.node-version }}
66+
67+
- name: Extract the version and commit body from the tag
68+
# The body may be multiline, therefore newlines and % need to be escaped
69+
run: |
70+
VERSION="${{ github.ref }}"
71+
VERSION=${VERSION##*/v}
72+
echo "::set-env name=VERSION::$VERSION"
73+
BODY=$(git show -s --format=%b)
74+
BODY="${BODY//'%'/'%25'}"
75+
BODY="${BODY//$'\n'/'%0A'}"
76+
BODY="${BODY//$'\r'/'%0D'}"
77+
echo "::set-env name=BODY::$BODY"
78+
79+
- name: Publish package to npm
80+
run: |
81+
npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
82+
npm whoami
83+
npm publish
84+
85+
- name: Create Github Release
86+
uses: actions/create-release@v1
87+
env:
88+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
89+
with:
90+
tag_name: ${{ github.ref }}
91+
release_name: Release v${{ env.VERSION }}
92+
draft: false
93+
# Prerelease versions create prereleases on Github
94+
prerelease: ${{ contains(env.VERSION, '-') }}
95+
body: ${{ env.BODY }}

‎CHANGELOG.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
# Changelog
2-
<!--
3-
Placeholder for the next version (add instead of version-number-headline below):
4-
## __WORK IN PROGRESS__
5-
-->
6-
## __WORK IN PROGRESS__
7-
* Initial release
1+
# Changelog
2+
<!--
3+
Placeholder for the next version (add instead of version-number-headline below):
4+
## __WORK IN PROGRESS__
5+
-->
6+
## 0.0.1 (2021-02-01)
7+
* Initial (beta) release
8+
* Created documentation

‎README-DEV.md‎

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,60 @@
1-
## Developer manual
2-
This section is intended for the developer. It can be deleted later
3-
4-
### Getting started
5-
6-
You are almost done, only a few steps left:
7-
1. Create a new repository on GitHub with the name `ioBroker.vis-3dmodel`
8-
1. Initialize the current folder as a new git repository:
9-
```bash
10-
git init
11-
git add .
12-
git commit -m "Initial commit"
13-
```
14-
1. Link your local repository with the one on GitHub:
15-
```bash
16-
git remote add origin https://github.com/Excodibur/ioBroker.vis-3dmodel
17-
```
18-
19-
1. Push all files to the GitHub repo:
20-
```bash
21-
git push origin master
22-
```
23-
24-
1. Head over to [widgets/vis-3dmodel.html](widgets/vis-3dmodel.html) and start programming!
25-
26-
### Best Practices
27-
We've collected some [best practices](https://github.com/ioBroker/ioBroker.repositories#development-and-coding-best-practices) regarding ioBroker development and coding in general. If you're new to ioBroker or Node.js, you should
28-
check them out. If you're already experienced, you should also take a look at them - you might learn something new :)
29-
30-
### Scripts in `package.json`
31-
Several npm scripts are predefined for your convenience. You can run them using `npm run <scriptname>`
32-
| Script name | Description |
33-
|-------------|----------------------------------------------------------|
34-
| `test:package` | Ensures your `package.json` and `io-package.json` are valid. |
35-
| `test` | Performs a minimal test run on package files. |
36-
37-
### Publishing the widget
38-
Since you have chosen GitHub Actions as your CI service, you can
39-
enable automatic releases on npm whenever you push a new git tag that matches the form
40-
`v<major>.<minor>.<patch>`. The necessary steps are described in `.github/workflows/test-and-release.yml`.
41-
42-
To get your widget released in ioBroker, please refer to the documentation
43-
of [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository).
44-
45-
### Test the adapter manually on a local ioBroker installation
46-
In order to install the adapter locally without publishing, the following steps are recommended:
47-
1. Create a tarball from your dev directory:
48-
```bash
49-
npm pack
50-
```
51-
1. Upload the resulting file to your ioBroker host
52-
1. Install it locally (The paths are different on Windows):
53-
```bash
54-
cd /opt/iobroker
55-
npm i /path/to/tarball.tgz
56-
```
57-
58-
For later updates, the above procedure is not necessary. Just do the following:
59-
1. Overwrite the changed files in the adapter directory (`/opt/iobroker/node_modules/iobroker.vis-3dmodel`)
1+
## Developer manual
2+
This section is intended for the developer. It can be deleted later
3+
4+
### Getting started
5+
6+
You are almost done, only a few steps left:
7+
1. Create a new repository on GitHub with the name `ioBroker.vis-3dmodel`
8+
1. Initialize the current folder as a new git repository:
9+
```bash
10+
git init
11+
git add .
12+
git commit -m "Initial commit"
13+
```
14+
1. Link your local repository with the one on GitHub:
15+
```bash
16+
git remote add origin https://github.com/Excodibur/ioBroker.vis-3dmodel
17+
```
18+
19+
1. Push all files to the GitHub repo:
20+
```bash
21+
git push origin master
22+
```
23+
24+
1. Head over to [widgets/vis-3dmodel.html](widgets/vis-3dmodel.html) and start programming!
25+
26+
### Best Practices
27+
We've collected some [best practices](https://github.com/ioBroker/ioBroker.repositories#development-and-coding-best-practices) regarding ioBroker development and coding in general. If you're new to ioBroker or Node.js, you should
28+
check them out. If you're already experienced, you should also take a look at them - you might learn something new :)
29+
30+
### Scripts in `package.json`
31+
Several npm scripts are predefined for your convenience. You can run them using `npm run <scriptname>`
32+
| Script name | Description |
33+
|-------------|----------------------------------------------------------|
34+
| `test:package` | Ensures your `package.json` and `io-package.json` are valid. |
35+
| `test` | Performs a minimal test run on package files. |
36+
37+
### Publishing the widget
38+
Since you have chosen GitHub Actions as your CI service, you can
39+
enable automatic releases on npm whenever you push a new git tag that matches the form
40+
`v<major>.<minor>.<patch>`. The necessary steps are described in `.github/workflows/test-and-release.yml`.
41+
42+
To get your widget released in ioBroker, please refer to the documentation
43+
of [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository).
44+
45+
### Test the adapter manually on a local ioBroker installation
46+
In order to install the adapter locally without publishing, the following steps are recommended:
47+
1. Create a tarball from your dev directory:
48+
```bash
49+
npm pack
50+
```
51+
1. Upload the resulting file to your ioBroker host
52+
1. Install it locally (The paths are different on Windows):
53+
```bash
54+
cd /opt/iobroker
55+
npm i /path/to/tarball.tgz
56+
```
57+
58+
For later updates, the above procedure is not necessary. Just do the following:
59+
1. Overwrite the changed files in the adapter directory (`/opt/iobroker/node_modules/iobroker.vis-3dmodel`)
6060
1. Execute `iobroker upload vis-3dmodel` on the ioBroker host

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Source files for this example can be found [here](examples/house).
2121

2222
This widget is in a very early and potentially unstable phase. Not all features have been implemented yet, so there will be a lot of bugs and "dead-ends" at the moment.
2323

24-
Before you start using it, please [read the documentation](https://github.com/Excodibur/ioBroker.vis-3dmodel/blob/master/doc/index.adoc).
24+
Before you start using it, please [read the documentation](https://excodibur.github.io/ioBroker.vis-3dmodel/latest/index.html).
2525

2626

2727
## Changelog

0 commit comments

Comments
 (0)