This repository contains AGL documentation tools to automatically generate a technical website from Markdown files.
The tool relies on https://jekyllrb.com and proposed scripts are largely inspired from https://github.com/apache/cordova-docs
This repository is handled by docs-webtemplate from https://github.com/automotive-grade-linux/docs-webtemplate.git with the script setupdocs.sh, please refer to it to initialise the doc environment.
- NodeJs+npm
- Ruby
- RubyGems
- Python
- Jekyll
Follow Jekyll instalation at https://jekyllrb.com/docs/installation/ Add Gem SCSS with "sudo gem install sass"
On OpenSuse on any other Linux plateform installation should be as simple as
sudo zypper install nodejs
check your nodejs version:
node --version
v4.6.1
You need a recent version of nodejs > 4.6
cd doctools/webdocs/
npm install
sudo zypper install ruby2.4-devel
sudo zypper install ruby2.4-rubygem-ffi
sudo gem.ruby2.4 install jekyll
sudo ln -sf /usr/bin/jekyll.* /usr/bin/jekyll
IMPORTANT: check that "jekyll" command exist.
jekyll -version
WARNING:
- would you choose to install everything through GEM bypassing your standard distribution package management, this may impose you to compile a couple of Ruby native extentions. If "gem install" fails you probably miss some required tools like: gcc, libffi-devel-gcc5, ...
- This command should display jekyll+rouge+sass :
gem search --local | grep -E "jekyll|rouge|sass"
jekyll (3.3.1)
jekyll-sass-converter (1.5.0)
jekyll-watch (1.5.0)
rouge (1.11.1)
sass (3.5.0.pre.rc.1)
sass-listen (3.0.7)
cd docs-agl/webdocs-agl
../doctools/webdocs/docbuild --verbose --clean --force --fetch
../doctools/webdocs/docbuild --verbose --build --serve --watch
point a browser on http://localhost:4000
xdg-open http://localhost:4000
--watch to automatically regenerate pages on markdown file, you should force "./build --configs" when changing TOC or versions.
- Search Engine https://community.algolia.com/docsearch/
- Markdown to HTML generation https://jekyllrb.com
- Scripts from Cordova http://cordova.apache.org/docs