Skip to content
This repository has been archived by the owner on Sep 27, 2024. It is now read-only.
/ blech-doc Public archive

Documentation for the Blech embedded programming language

License

Notifications You must be signed in to change notification settings

boschresearch/blech-doc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blech documentation

Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

Project Status: Moved to http://github.com/blech-lang/blech-doc – The project has been moved to a new location, and the version at that location should be considered authoritative. to development.blech-lang.org

Documentation for the Blech embedded programming language. Read the documentation on the new homepage.

If you want to change the contents of that website read the following to get started.

The necessary tool chain to build the documentation and the website consists of

  • Hugo, the static website generator,
  • Docsy, the Hugo documentation theme,

Installing the tool chain for this repository

On windows we recommend Chocolatey for the installation of Hugo.

For chocolatey we recommend the non-administrative install. In a corporate setup behind a proxy use the corresponding options.

From time to time run an upgrade.

choco upgrade chocolatey

Install Hugo - the static site generator

Install the extended version of Hugo. The extended version is necessary for the Docsy theme.

Details can be found in the Hugo Installation documentation

On windows we recommend to install Hugo with Chocolatey.

choco install hugo-extended -confirm

Test it

hugo version

You should see /extented behind the version number. Now you are ready to work with the repository.

Working with the repository

The Blech documentation already contains the Docsy theme as a git submodule. For more information see the Docsy Getting Started Documentation. Therefore clone in the following way:

git clone --recurse-submodules --depth 1 https://github.com/boschresearch/blech-doc.git

Install local npm modules

You need to install the following npm modules locally to the /website directory of the repository. You must have a recent version of NodeJS installed on your machine to use npm.

npm is frequently updated. In order to keep up-to-date run:

npm install npm@latest -g

To install the necessary npm modules go to the website subfolder in your cloned repository.

cd blech-doc/website

Locally install the npm modules autoprefixer, postcss-cli and postcss.

npm install -D autoprefixer
npm install -D postcss-cli
npm install -D postcss

Update the Docsy theme

The Hugo Docsy theme is frequently updated. From time to time update the Docsy theme submodule.

From the root of your repository run:

git submodule update --remote

Preview the website

Change to the ./website subdirectory.

cd website

Run the website without static site generation

hugo server

Use options -D and -F to preview draft and future content:

hugo -D -F server

Open the Blech site preview: http://localhost:1313/blech-doc

Publish the static website content

The static website content is generated into the /docs folder of the repository. In order to get a clean content, we recommend to delete the /docs folder before creating the content.

From top of the repository run

rm -r docs

The content can be generated from the commandline. Change to subfolder ./website/scripts.

cd website/scripts

and run

./build.[sh, bat]

The website is deployed as a GitHub Project Page. For simplicity, we deploy the project pages from the /docs folder on the master branch

For publishing just push the content of the /docs folder to the master branch.

Give GitHub some time to deploy the content and open the Blech site on https://boschresearch.github.io/blech-doc

Check for broken links on the website

In order to check the links on the website you can use the npm package broken link checker.

Install it with

npm install broken-link-checker -g

Test the installation

blc --help

Check the whole Blech website with

blc https://boschresearch.github.io/blech-doc -ro

The last command only works in a network with commandline DNS access, i.e. without a proxy.

Creating content

The documentation for the Docsy Theme explains how to create content.

Creating a blog post is easy. The Docsy example site shows how to do this.

About

Documentation for the Blech embedded programming language

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages