qskinny/doc/generate-website.md

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 .
2. 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.
3. 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 .
4. 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.
5. 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.
2. 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.
3. 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.