70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
|
# 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.
|