## How to contribute to this documentation

Here we explain how to edit this documentation locally and submit changes for online publication.

### General information

This web site is generated using the static site generator Hugo. Sources are mostly writen in the MarkDown format. Hugo translates them into HTML.

To submit improvements of the documentation proceed as follows:

### Install Hugo

Install Hugo either using a package manager, or directly from upstream: Download the archive file for your platform from https://github.com/gohugoio/hugo/releases . This archive contains a single binary. Put it into a directory that is in your PATH.

### Run Hugo locally

Go to cloned repository and run Hugo.

    $ cd BornAgain/hugo
    $ hugo server -D

Hugo will print a line like

    Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

Point your web browser to that URL (most often `http://localhost:1313/`). You should see a local copy of the BornAgain home page. From there you should be able to navigate through the entire BornAgain documentation.

Keep the Hugo server running while modifying documentation source files.

### Modify the documentation

The documentation sources are in directory `hugo/content/`. They consist of Markdown files. For example, the source of the page you are looking at right now, is

    content/developers-corner/contribute-to-documentation.md

Create a feature branch to work on:

    $ git checkout -b my_feature

where `my_feature` should describe what you want to improve.

Edit any source file. Your local Hugo will then update the web site within a fraction of a second.

Whenever you made a significant change, commit it to your feature branch:

    $ git commit

### Check all links

Run

    $ hugo server --disableFastRender

to create a website under an address like `http://localhost:1313/git-develop/`.

If checkout from the older release branch `rVersion`, the address will be `http://localhost:1313/Version/`.

Here and below `Version` is the version number or “git-develop”.

Install `linkchecker` (Debian package has same name). Run

    $ linkchecker http://localhost:1313/Version/

The operation may take few minutes.

Ignore the warnings. Resolve the errors. Submit MR against corresponding branch.

### Submit a merge request

Confine work to one topic. For other topics, start new feature branches.

When one feature branch is ready for review, push it to our git server:

    $ git push

This requires developer access, which we will grant you upon informal request.

The terminal output will contain a message like

    remote: To create a merge request for test, visit:
    remote:   https://jugit.fz-juelich.de/mlz/bornagain/-/merge_requests/new?merge_request%5Bsource_branch%5D=my_feature
    remote:

Login to Jugit. Visit the indicated URL to open a Merge Request.

### Update visible pages

After the MR is merged, login to the web server and go to the hugo directory:

    $ cd ba/Version/repo/hugo

Make sure you are on the right branch. Do

    $ git pull --all

Run hugo. Check that the changes are online at `bornagainproject.org/Version`.

- Introduction
  - Functionality overview
  - Architectural overview

- Install or build
  - Install Python
    - Python on Linux
    - Python on Windows
    - Python on Mac
    - Python modules
  - Install BornAgain
    - Linux
    - Windows
    - MacOS
    - Development snapshot
  - Build BornAgain
    - Unix
      - Install third-party software
      - Get the source
      - Build and install BornAgain
      - Run a first simulation
    - Windows

- Graphical user interface
  - Quick Start
  - GUI overview
  - Fitting in the GUI

- Python scripting
  - Run a script
  - Understand the syntax
  - Fitting
  - Upgrading

- Reference
  - Simulation model
    - Simulation classes
      - Specular
        - Example
      - Scattering
        - Examples
          - GISAS
          - without DWBA terms
          - with specular peak
          - SAS
          - Polarized SANS
          - Monte-Carlo
      - Off-specular
        - Off-specular
      - Depth probe
        - Examples
          - Thin film
          - Transmitted modulus
          - Resonator
    - Common settings
      - Background
      - Options
        - Monte-Carlo
        - # threads
        - Average materials
        - Include specular
      - Progress monitor
  - Instrument model
    - Beam
      - Footprint
      - Beam divergence
    - Scan
      - TOF reflectometry
      - TOF resolution
      - Beam Angular Spread
      - Beam Wavelength Spread
    - Detectors
      - SphericalDetector
      - 2d detector resolution
      - Offspec detector
    - Neutron polarization
      - Spin asymmetry example
    - Examples
      - 2D detector resolution
      - Neutron polarization
        - Magnetic layer
        - Ditto, realistic instrument
        - Polarized scattering
  - Sample model
    - Materials
      - Magnetization
    - Sample
      - Layer
      - LayerStack
      - Layout
    - Roughness
      - Interface model
      - Transient
      - Cross-correlation
      - Examples
        - GISAS
        - Reflectivity
    - Particles
      - Form factor
        - Hard particles
          - Bipyramid4
          - Box
          - CantellatedCube
          - Cone
          - Cylinder
          - Dodecahedron
          - EllipsoidalCylinder
          - HemiEllipsoid
          - HorizontalCylinder
          - Icosahedron
          - PlatonicOctahedron
          - PlatonicTetrahedron
          - Prism3
          - Prism6
          - Pyramid2
          - Pyramid3
          - Pyramid4
          - Pyramid6
          - Sphere
          - SphericalSegment
          - Spheroid
          - SpheroidalSegment
          - TruncatedCube
        - Ripples
          - Bar ripple
          - Cosine ripple
          - Sawtooth ripple
        - Soft particles
          - FuzzySphere
          - Gauss
        - Custom formfactor
      - Composite particles
        - Core and shell
        - Compound particle
        - Mesocrystal
      - Examples
        - Compound particle
        - Core and shell
        - Crossing an interface
        - Mesocrystal
        - Rotation example
        - Dense cylinders
        - Dense hemispheres
        - Uncorrelated mixture
        - Polydispersity
    - Particle assemblies
      - Grating
        - 1D lattice
        - Cosine ripples in a lattice
        - Triangular ripples in a lattice
      - 2D lattice
        - Square lattice
        - Lattice orientation distribution
        - Finite square lattice
        - Lattice with basis
        - Multi-layer lattice
        - Position variance
      - Radial paracrystal
      - 2D paracrystal
      - Others
        - Size-distribution model: decoupling approximation
        - Size-distribution model: local monodisperse approximation
        - Size-distribution model: size-spacing coupling approximation
  - Model modifiers
    - Rotation
    - Distributions
  - Data types
    - Class Datafield
      - Export
      - Find intensity peaks
    - SLD profile
      - SLD profile with rough interfaces
      - SLD profile with a sliced particle layer
  - Plotting
    - Functions
    - Configuration
    - Heat map
    - LaTeX markup
    - Export
    - Plot axes in different units
  - Fitting
    - Data import
      - TIFF
    - Minimizer settings
    - Multiple datasets
    - Examples
      - Fitting with masks
      - Custom objective function
      - Fitting along slices
      - GISAS 2D fits
      - Experiment at GALAXI
      - Find background
      - Minimizer settings
      - Bayesian Sampling
      - Consecutive fitting
      - Considering uncertainties
      - External minimizer
      - External minimizer: plotting
      - Simultaneous fit of two datasets
      - Spin asymmetry fit example
      - Reflectometry: Fit Pt layer
      - Reflectometry: Fit honeycomb

- Literature
  - Babonneau2010
  - Babonneau2013
  - Croset2021
  - Lazzari2002
  - Lazzari2006
  - Pospelov2020
  - Renaud2009
  - Sears1992
  - Wuttke2021

- How to
  - Get announcements
  - Solve known problems
    - Set Python environmental variables under Windows
  - Request help or report bugs
  - Cite BornAgain

- Developers' corner
  - Configure
    - Build
    - Pyenv
  - Develop
    - Manual checks
    - Debug
    - Webdoc
    - Code analyses
  - Release
    - Manual GUI test