Snom io documentation website
Tools and build process
The website is built usking mkdocs a static documentation website generator Build process is done via the Makefile all the required tools to build the website (mkdocs, python etc..) are installed into a Docker container (see the docker/Dockerfile)
You can build the Docker image using the
make dbuild command (image name is defined via the
DOCKER_IMAGE Makefile variable).
Some files (like some public XML examples) need to be generated at build time in order to replace some placeholders (like for example the public URL).
In order to make ti process working you have to define the replace varilabes in the Makefile, variable names must start with
TPL_ variable replacement is done via the bash script in scripts/preprocessor.sh.
make prebuildpre-process the template files and generate the files
make buildcreates the static webiste under the
make servecreates the static webiste and start serving it using the mkdocs builting webserver
make gh-pagescreates the static website, commit the site into the
gh-pagesbranch and push the commit to Github. NOTE: Never do a commit on the gh-pages brach: your commmit will be lost after the next deploy. Use instead
This website is using the mkdocs-bootstrap-snom theme: a mkdocs-bootstrap modified theme.
Main changes are:
- breadcrumb bar
- possibility to hide pages from the navbar using a page name starting with hidden
- multilevel navbar and toc
Deploying the website locally
Thanks to the pre-processing mechanism all the provided examples are woring directly from the published pages. If for some reasons you want to re-deploy the whole site and examples in a your server you have to:
- Clone this repository
- Change the
TPL_ROOT_URLaccording with your webserver IP / name and root path
- Build the website using
make buildif you want to serve the
sitedirectory using your own web server. If you want to serve the pages using the Mkdocs builtin webserver you have to run
NOTE: In order to deploy the site you need Docker installed, otherwise you have do slightly modify the Makefile in order to use Mkdocs directly (all the requiremnts are listed in Docker/requirements.txt)