From 7d7e5a297a8560239781d7ac2a504f0500506720 Mon Sep 17 00:00:00 2001 From: Christoph Date: Wed, 28 Aug 2024 16:37:16 +0200 Subject: [PATCH] Tweaks for docs and add howto Signed-off-by: Christoph Rueger small rearrangments to sidebar - pulling content higher up which might be interesting for new users - merge sections "Introduction" and "Installation" into "Getting started" and add FAQ too clear caches on startup of jekyll server helps e.g. when making changes to sidebar Signed-off-by: Christoph Rueger adding summary sentence to front page Signed-off-by: Christoph Rueger improve manual fix link Signed-off-by: Christoph --- docs/README.md | 25 +++++++++++++++++++++++++ docs/_chapters/120-install.md | 2 +- docs/_data/sidebar.yml | 10 +++------- docs/_layouts/front.html | 10 ++++++++++ docs/run.sh | 1 + 5 files changed, 40 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index d0de167d10..47aa636765 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,3 +20,28 @@ using [GitHub Pages](https://help.github.com/articles/what-are-github-pages/). # Build it ./build.sh ``` + +## Setup local docs development environment (MacOS) + +If you get an error like `activesupport-7.0.7.2 requires ruby version >= 2.7.0, which is incompatible with the current version, ruby 2.6.10p210` when executing `./run.sh` then consider doing the following: + +- Install rbenv Ruby Version manager https://github.com/rbenv/rbenv e.g. via brew +- and then use it to install and use e.g. ruby 3.1.2 + +``` +brew install rbenv +rbenv init +rbenv install 3.1.2 +rbenv global 3.1.2 +./run.sh +``` + +After a successfull start of `./run.sh` you see this: + +``` +Server address: http://127.0.0.1:4000 +Server running... press ctrl-c to stop. +``` + +Open http://127.0.0.1:4000 in your browser to see the result while developing. +The server does support hot-reload so you should see changes to `.md` files immediately without restart (there are a few exceptions). Checkout the [jekyll-docs](https://jekyllrb.com/docs/pages/) to get more into the details and features. diff --git a/docs/_chapters/120-install.md b/docs/_chapters/120-install.md index b25c2d2f46..ae08857f1e 100644 --- a/docs/_chapters/120-install.md +++ b/docs/_chapters/120-install.md @@ -47,7 +47,7 @@ The manual is also on [github][5]. If you see an improvement, do not hesitate to If you're behind a firewall that requires proxies or you use repositories that require authentication see [-connection-settings][6]. -[1]: https://brew.sh/ +[1]: https://formulae.brew.sh/formula/bnd [3]: https://github.com/bndtools/bnd [4]: https://bndtools.jfrog.io/bndtools/libs-snapshot [5]: https://github.com/bndtools/bnd/tree/master/docs diff --git a/docs/_data/sidebar.yml b/docs/_data/sidebar.yml index aff5f4837e..48476c2058 100644 --- a/docs/_data/sidebar.yml +++ b/docs/_data/sidebar.yml @@ -1,16 +1,13 @@ nav: - - title: Introduction - subfolderitems: - - url: /chapters/110-introduction.html - - title: Installation - subfolderitems: - - url: /chapters/120-install.html - title: Getting Started subfolderitems: + - url: /chapters/120-install.html - url: /chapters/123-tour-workspace.html - url: /chapters/125-tour-features.html + - url: /chapters/920-faq.html - title: Concepts and Practices subfolderitems: + - url: /chapters/110-introduction.html - url: /chapters/130-concepts.html - url: /chapters/140-best-practices.html - title: Build and Development @@ -62,4 +59,3 @@ nav: - url: /chapters/880-settings.html - url: /chapters/900-errors.html - url: /chapters/910-warnings.html - - url: /chapters/920-faq.html diff --git a/docs/_layouts/front.html b/docs/_layouts/front.html index 10a73ea922..278f44118b 100644 --- a/docs/_layouts/front.html +++ b/docs/_layouts/front.html @@ -11,6 +11,16 @@ +
+

Bnd is a tooling suite for building OSGi bundles. + Its primary function is generating OSGi meta data by analyzing Java classes. +
+ There are plugins for popular tools like Eclipse, Maven and Gradle. +

+
+ + +

  • What is bnd?

    diff --git a/docs/run.sh b/docs/run.sh index e7180b0d9e..6924950e6e 100755 --- a/docs/run.sh +++ b/docs/run.sh @@ -3,5 +3,6 @@ set -ev export BUNDLE_GEMFILE=$PWD/Gemfile bundle install --jobs=3 --retry=3 +bundle exec jekyll clean bundle exec jekyll serve -w --incremental