README.md 8.53 KB
Newer Older
1
# Requirements
2

3
You need these tools installed:
4
* git-lfs from https://git-lfs.github.com/
5
* hugo from https://github.com/spf13/hugo/releases
6

7 8
# Setup

Steffen Müthing's avatar
Steffen Müthing committed
9
**IMPORTANT: INSTALL GIT-LFS BEFORE COMMITTING ANYTHING TO THIS REPOSITORY!!!!!!!!**
10

11 12 13 14 15 16 17 18
## git-lfs

After installing the dependencies, you need to make sure git-lfs is working correctly. For this purpose, run the following command in a terminal:
```
git lfs install
```
This command will set up the required hooks and filters in your configuration to integrate git-lfs with git.

19 20
## Cloning the repository

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
If you simply clone the repository you will be asked to give your
password for every file downloaded with git-lfs. You can avoid that by
using an ssh agent (if you use ssh) or by setting up the credential
helper (if you use https).

### Using ssh

Use an ssh agent to store your ssh key and clone as usual. With linux
you can probably use:

```
ssh-add
git clone ssh://git@gitlab.dune-project.org:22022/infrastructure/dune-website.git
```

### Using https

#### Cloning
Use the following commands to clone the repository without the lfs
files:

42 43 44 45 46
```
git clone --config lfs.fetchexclude=static https://gitlab.dune-project.org/infrastructure/dune-website.git
cd dune-website
git config --unset lfs.fetchexclude
```
47

48 49
#### Credential helper
Now we set up a [credential helper](https://git-scm.com/docs/gitcredentials) that will supply it with the username and password
50 51 52 53 54
for gitlab.dune-project.org. There are multiple options, depending on your operating system:

* On Linux, you can either use the **credential cache** or the **credential store**:

    * The **credential cache** keeps your credentials in memory for a short while. If you want to use this, you will have to feed
Steffen Müthing's avatar
Steffen Müthing committed
55
      the credentials to the cache rather often.
56 57

    * If you don't want git to permanently remember your password, you can use the **credential store**. Note, however, that it stores
58
      the password in unencrypted form on your hard drive, so you probably want to use this only for selected remotes.
Steffen Müthing's avatar
Steffen Müthing committed
59 60 61 62 63

    Irrespective of which helper you want to use, you first have to set it up by running the following command in the dune-website repository:
    ```
    git config [--global] credential.helper [cache/store]
    ```
64 65 66 67
    To enable the helper only for remotes hosted on Dune's gitlab instance, use
    ```
    git config --global credential.https://gitlab.dune-project.org.helper [cache/store]
    ```
Steffen Müthing's avatar
Steffen Müthing committed
68 69
    If you add the `--global` option, git will use the same credential helper for all repositories on your machine.

70
    Afterwards, you have to run the script [bin/update-gitlab-credentials](bin/update-gitlab-credentials) to add your GitLab credentials
Steffen Müthing's avatar
Steffen Müthing committed
71 72
    to the helper.

73
    **Important**: If you are using the cache, you have to run [bin/update-gitlab-credentials](bin/update-gitlab-credentials) **every time** before
Steffen Müthing's avatar
Steffen Müthing committed
74
    you talk to the server (`git pull`, `git push` etc.).
75 76 77 78 79 80

* On macOS, git ships with a credential helper that integrates with the system keychain for encrypted password storage. You can enable
  that cache globally by running
  ```
  git config --global credential.helper osxkeychain
  ```
81
  Afterwards, you can store your credentials by running the script [bin/update-gitlab-credentials](bin/update-gitlab-credentials) once.
82

83
#### Finishing up
84 85 86 87 88 89 90 91

After you have set up the credential helper and storing the credentials in the helper by running
[bin/store-gitlab-credentials](bin/store-gitlab-credentials), run the following command to finish up the repository setup:
```
git lfs pull
```
This will download all of the large binary files.

92
# Building
Steffen Müthing's avatar
Steffen Müthing committed
93
Having installed these requirements, type in the toplevel directory of dune-website:
94 95 96 97 98
```
hugo server --watch
```
This will spin up a webserver, allowing you to browse the page. The page will
update itself as soon as you apply any changes to the sources.
99

100 101 102 103 104
## Building the documentation

Building the documentation is done with the help of [ciwebsitebuilder](https://gitlab.dune-project.org/infrastructure/ci-website-builder). Please check out that project if you want to build the documentation locally on your machine.

The documentation part of the website gets updated as part of a scheduled build that runs every night. Building the documentation takes a lot of time, so we skip it for normal integration testing and deployment. If you have a branch that makes changes to the Doxygen or the sphinx documentation, you can force GitLab to test those parts by prepending one or both of `doxygen/` and / or `sphinx/` to the branch name (if you can, please also test the changes locally using `ciwebsitebuilder`). As an example, if you want to add Doxygen documentation for Dune 2.6.0, call the branch `features/doxygen/core-modules-release-2.6.0`. This will cause the merge request to test Doxygen and Sphinx documentation, but deployment to the website will still only happen during the nightly build.
105

106 107
A nightly build with documentation can also be manually triggered by clicking the triangular "Play" button next to the schedule on the [Schedules](https://gitlab.dune-project.org/infrastructure/dune-website/pipeline_schedules) page, provided you have sufficient permissions.

108 109 110 111 112 113 114 115 116 117
# Directory structure
The following subdirectories of a hugo project are relevant when adding content:
* the contents folder contains content in form of markdown files.
  Each markdown file has a so-called front matter (separated by +++), that
  contains metadata of the page. For most normal contents, it is sufficient
  to specify the Title there. The structure within the content subdir
  is translated into the directory structure of the built homepage.
  (./content/about/dune.md appears at www.dune-project.org/about/dune)
* the static folder contains all sorts of static data. Git LFS is used
  to add binary data. You can simply commit big pdfs or tarballs, no problem.
118

119
# Archetypes
120

121 122 123 124
The following contents are managed through so called archetypes (see archetypes subdir):
* News items (called "news")
* Releases (called "releases")
* Dune Modules (called "modules")
125

126 127 128
Whenever you want to add content of a given archetype you can either
* `hugo new <archetype>/<name>.md` and then edit the newly generated file
* `cp archetypes/<archetype>.md content/<archetype>/<name>.md` and then edit
129 130 131 132 133

Both these approaches have their pros and cons. The former will automatically
add a `Date` field to the generated file, which is needed for the sorting of
news items. Then again, the latter preserves comments in the archetype frontmatter
(which help a lot in understanding the doxygen build process).
134

135
## News items
136

137
News items work exactly as before. The timestamp is automatically added to the front matter.
138

139 140 141 142 143 144 145
## Releases

The process of publishing a Dune releases is (or will be, as we will test all that with 2.4.1)
kind of automated through the releases archetype. The download section is populated automatically,
the markdown content is just the release notes. The menu automatically chooses the latest 3 releases
to link directly (excluding outdated point releases).

146 147
To add a new release, have a look at `bin/add_release.py`.

148 149 150 151 152 153 154 155
## Modules

I added an archetype "modules" to document dune modules. This has the following effects:
* Each dune module has its own content page, just as some chosen few had before (the discretization
  modules, dune-grid-glue, dune-mc, dune-functions etc.)
* A module summary is automatically shown in the corresponding module group (check the menu!)
* Crosslinking to all requirements etc.
I would like this to become some sort of a database of available dune modules.
156

157 158 159 160 161
To add new module to the "database" proceed as follows:
* `cp archetypes/modules.md content/modules/dune-foo.md` in the top-level directory
* Open content/modules/dune-foo.md and carefully read through the frontmatter and fill in the missing information.
* Write a text of arbitrary length and amount of detail below the frontmatter in markdown!

162
# Doxygen
163

164 165
Building the doxygen documentation is done from the project dune-website-builder.
The documentation building is triggered through tags in the frontmatter of either releases
166 167 168
or dune modules. Please read through the frontmatter of the modules archetype for details!

Doxygen documentation is currently built nightly through a cronjob!
169

170
# Online Editing
171 172 173 174 175
Many developers asked for an "online editing" system. This is
available through the small editing button in the top right of the
page. This is only possible for single content pages (e.g
https://beta.dune-project.org/about/dune/).  It uses gitlabs online
editing system.
176

177
# More information
178

179
The docs at www.gohugo.io are a good read.
180

181 182
If you have specific questions please contact
Dominic Kempf <dominic.kempf@iwr.uni-heidelberg.de>