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

update instructions on how to build the website

This commit is contained in:
Peter Hartmann 2024-11-12 10:19:53 +01:00
parent 5f3ab365a4
commit 85f7bb8800
1 changed files with 46 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
doc/generate-website.md
View File

@ -4,66 +4,65 @@
You will need: You will need:
1. The `documentation-xml-website` branch of the Edelhirsch QSkinny repository 1. A recent version of doxygen; The currently used version is 1.9.8.
at https://github.com/edelhirsch/qskinny/tree/documentation-xml-website . The `doxygen` binary needs to be in the $PATH.
1. A recent version of doxygen; The currently used version is 1.9.1 built from 1. The `m4` command, which can be installed with `sudo apt install m4`.
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 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 the static html pages. The currently used jekyll version is 4.2.2.
Also a recent version of bundler is required; this can be installed with:
``` ```
gem install jekyll:3.9.0 gem install jekyll:4.2.2
gem install bundler:2.1.4 gem install bundler:2.1.4
``` ```
There might be some packages missing from the list above; in this case the 1. Checkout the repo to generate the website via
Gemfile in the qskinny-website repository might help. `git clone git@github.com:peter-ha/qskinny-website.git`
1. Checkout the current website repository via 1. Checkout the live website repository via
`git clone git@github.com:qskinny/qskinny.github.io.git` `git clone git@github.com:qskinny/qskinny.github.io.git`
## Generating the website ## Generating the website
Generating the static HTML sites is done with the `generate-website.sh` script ### Generating the API documentation with doxygen
in the `qskinny/doc` directory. The script has some hardcoded paths and probably ```
needs some adaptation to run correctly. cd ~/dev/qskinny/doc
export PATH=.:$PATH
doxygen
```
This will generate the documentation into the `api` folder.
It will do the following: ### Testing and building the website locally
1. Generate HTML from doxygen. This step is needed because for some reason when First copy the generated files from above to the website repo:
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 ```
cp -r api ~/dev/qskinny-website/docs/
```
When the command line switch `-local` is used with the `generate-website.sh` Then test the website locally:
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 ```
cd ~/dev/qskinny-website
bundle exec jekyll serve --livereload
```
After having generated the website as described above, go to Then direct your browser to `http://127.0.0.1:4000/`.
`~/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 If all looks good, generate the static HTML website:
When the command line switch `-publish` is used, the script will automatically ```
generate a new version of the homepage and publish it at bundle exec jekyll build
https://qskinny.github.io . This wil only work with the proper user rights of ```
course.
### Publishing the website
Just copy over the generated HTML files to the public website repo and push a
new version of the homepage:
```
cp -r _site/* ~/dev/qskinny.github.io/
cd ~/dev/qskinny.github.io/
git commit -a -m "new version" # you might want to add new files
gith push
```
That's it, the new website is now published at https://qskinny.github.io/ .