From 6a84d4197f01ecf0e1ed7eaba2c9455e428d2fe1 Mon Sep 17 00:00:00 2001 From: Peter Hartmann Date: Wed, 13 Apr 2022 21:06:24 +0200 Subject: [PATCH] website: Add README on how to recreate the website (#179) Resolves #171 --- doc/generate-website.md | 69 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 doc/generate-website.md diff --git a/doc/generate-website.md b/doc/generate-website.md new file mode 100644 index 00000000..121afe27 --- /dev/null +++ b/doc/generate-website.md @@ -0,0 +1,69 @@ +# Generating the website + +## Prerequisites + +You will need: + +1. The `documentation-xml-website` branch of the Edelhirsch QSkinny repository + at https://github.com/edelhirsch/qskinny/tree/documentation-xml-website . +1. A recent version of doxygen; The currently used version is 1.9.1 built from + github sources. The `doxygen` binary needs to be in the $PATH. +1. A recent version of doxybook2 with some custom patches. The script + `generate-website.sh` should download and build the right version, however + the script might need some adaptation of paths. + For reference, the required version can be found at + https://github.com/edelhirsch/doxybook2/tree/jekyll . +1. A recent version of Jekyll (see https://jekyllrb.com/), which will generate + the static html pages. This and other required packages can be installed via + ``` + gem install jekyll:3.9.0 + gem install bundler:2.1.4 + ``` + There might be some packages missing from the list above; in this case the + Gemfile in the qskinny-website repository might help. +1. Checkout the current website repository via + `git clone git@github.com:qskinny/qskinny.github.io.git` + +## Generating the website + +Generating the static HTML sites is done with the `generate-website.sh` script +in the `qskinny/doc` directory. The script has some hardcoded paths and probably +needs some adaptation to run correctly. + +It will do the following: + +1. Generate HTML from doxygen. This step is needed because for some reason when + generating XML from doxygen there are no images with dependency graphs. + *Note*: This step is only executed if the `html` folder doesn't exist, + because otherwise it would take too long. +1. Generate XML from doxygen. The generated XML is used with doxybook2 in the + next step. + *Note*: This step is only executed if the `xml` folder doesn't exist, + because otherwise it would take too long. +1. Generate markdown from XML with doxybook2. This markdown will be used by + Jekyll to either server the website content locally or generate static + HTML from it, see below. + +### Generating the website locally + +When the command line switch `-local` is used with the `generate-website.sh` +script, it will generate the content to a local folder `doxybook-out`. This is +meant to be able to copy selected files to the website directory at +`~/dev/qskinny-website`. +Otherwise, the script will copy the content to the website repository for +uploading (again, paths are hardcoded as of now). So when generating content +for the first time, just run the script without any switches, which should +generate the website to `~/dev/qskinny-website`. + +### Testing the website locally + +After having generated the website as described above, go to +`~/dev/qskinny-website` and run `jekyll serve --livereload`. This should start +a browser at http://127.0.0.1:4000/, which will display the website. + +### Generating the website publicly + +When the command line switch `-publish` is used, the script will automatically +generate a new version of the homepage and publish it at +https://qskinny.github.io . This wil only work with the proper user rights of +course.