peranger/qskinny
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website: Add README on how to recreate the website (#179)

Browse Source 
Resolves #171
This commit is contained in:
Peter Hartmann 2022-04-13 21:06:24 +02:00 committed by GitHub
parent 6d9dcbcf91
commit 6a84d4197f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 69 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
doc/generate-website.md Normal file
View File

@ -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.