Huge improvements for docs (#58)

docs/content/doc/development/development.md

@@ -0,0 +1,61 @@
+---
+date: "2019-02-12:00:00+02:00"
+title: "Development"
+toc: true
+draft: false
+type: "doc"
+menu:
+  sidebar:
+    parent: "development"
+    name: "Development"
+---
+
+# Development
+
+We use go modules to vendor libraries for Vikunja, so you'll need at least go `1.11` to use these.
+If you don't intend to add new dependencies, go `1.9` and above should be fine.
+
+To contribute to Vikunja, fork the project and work on the master branch.
+
+A lot of developing tasks are automated using a Makefile, so make sure to [take a look at it]({{< ref "make.md">}}).
+
+## Libraries
+
+We keep all libraries used for Vikunja around in the `vendor/` folder to still be able to build the project even if
+some maintainers take their libraries down like [it happened in the past](https://github.com/jteeuwen/go-bindata/issues/5).
+
+## Tests
+
+See [testing]({{< ref "test.md">}}).
+
+#### Development using go modules
+
+If you're able to use go modules, you can clone the project wherever you want to and work from there.
+
+However, when building or running tests, please supply the `-mod=vendor` flag to go so it builds using the 
+dependencies from the `vendor/` folder.
+
+#### Development-setup without go modules
+
+Some internal packages are referenced using their respective package URL. This can become problematic. 
+To “trick” the Go tool into thinking this is a clone from the official repository, download the source code 
+into `$GOPATH/code.vikunja.io/api`. Fork the Vikunja repository, it should then be possible to switch the source directory on the command line.
+
+{{< highlight bash >}}
+cd $GOPATH/src/code.vikunja.io/api
+{{< /highlight >}}
+
+To be able to create pull requests, the forked repository should be added as a remote to the Vikunja sources, otherwise changes can’t be pushed.
+
+{{< highlight bash >}}
+git remote rename origin upstream
+git remote add origin git@git.kolaente.de:<USERNAME>/api.git
+git fetch --all --prune
+{{< /highlight >}}
+
+This should provide a working development environment for Vikunja. Take a look at the Makefile to get an overview about 
+the available tasks. The most common tasks should be `make test` which will start our test environment and `make build` 
+which will build a vikunja binary into the working directory. Writing test cases is not mandatory to contribute, but it 
+is highly encouraged and helps developers sleep at night.
+
+That’s it! You are ready to hack on Vikunja. Test changes, push them to the repository, and open a pull request.

docs/content/doc/development/make.md

@@ -0,0 +1,132 @@
+---
+date: "2019-02-12:00:00+02:00"
+title: "Makefile"
+draft: false
+type: "doc"
+menu:
+  sidebar:
+    parent: "development"
+---
+
+# Makefile
+
+We scripted a lot of tasks used mostly for developing into the makefile. This documents explains what
+taks are available and what they do.
+
+## CI
+
+These tasks are automatically run in our CI every time someone pushes to master or you update a pull request:
+
+* `make lint`
+* `make fmt-check`
+* `make ineffassign-check`
+* `make misspell-check`
+* `make goconst-check`
+* `make build`
+
+### clean
+
+{{< highlight bash >}}
+make clean
+{{< /highlight >}}
+
+Clears all builds and binaries.
+
+### test
+
+{{< highlight bash >}}
+make test
+{{< /highlight >}}
+
+Runs all tests in Vikunja.
+
+### Format the code
+
+{{< highlight bash >}}
+make fmt
+{{< /highlight >}}
+
+Formats all source code using `go fmt`.
+
+#### Check formatting
+
+{{< highlight bash >}}
+make fmt-check
+{{< /highlight >}}
+
+Checks if the code needs to be formatted. Fails if it does.
+
+### Build Vikunja
+
+{{< highlight bash >}}
+make build
+{{< /highlight >}}
+
+Builds a `vikunja`-binary in the root directory of the repo for the platform it is run on.
+
+### Build Releases
+
+{{< highlight bash >}}
+make build
+{{< /highlight >}}
+
+Builds binaries for all platforms and zips them with a copy of the `templates/` folder.
+All built zip files are stored into `dist/zips/`. Binaries are stored in `dist/binaries/`,
+binaries bundled with `templates` are stored in `dist/releases/`.
+
+All cross-platform binaries built using this series of commands are built with the help of 
+[xgo](https://github.com/karalabe/xgo). The make command will automatically install the
+binary to be able to use it.
+
+`make release` is actually just a shortcut to execute `make release-dirs release-windows release-linux release-darwin release-copy release-check release-os-package release-zip`.
+
+* `release-dirs` creates all directories needed
+* `release-windows`/`release-linux`/`release-darwin` execute xgo to build for their respective platforms
+* `release-copy` bundles binaries with a copy of `templates/` to then be zipped
+* `release-check` creates sha256 checksums for each binary which will be included in the zip file
+* `release-os-package` bundles a binary with a copy of the `templates/` folder, the `sha256` checksum file, a sample `config.yml` and a copy of the license in a folder for each architecture
+* `release-zip` makes a zip file for the files created by `release-os-package`
+
+### Build debian packages
+
+{{< highlight bash >}}
+make build-deb
+{{< /highlight >}}
+
+Will build a `.deb` package into the current folder. You need to have [fpm](https://fpm.readthedocs.io/en/latest/intro.html) installed to be able to do this.
+
+#### Make a debian repo
+
+{{< highlight bash >}}
+make reprepro
+{{< /highlight >}}
+
+Takes an already built debian package and creates a debian repo structure around it.
+
+Used to be run inside a [docker container](https://git.kolaente.de/konrad/reprepro-docker) in the CI process when releasing.
+
+### Generate swagger definitions from code comments
+
+{{< highlight bash >}}
+make do-the-swag
+{{< /highlight >}}
+
+Generates swagger definitions from the comments in the code.
+
+#### Check if swagger generation is needed
+
+{{< highlight bash >}}
+make got-swag
+{{< /highlight >}}
+
+This command is currently more an experiment, use it with caution.
+It may bring up wrong results.
+
+### Code-Checks
+
+* `misspell-check`: Checks for commonly misspelled words
+* `ineffassign-check`: Checks for ineffectual assignments in the code using [ineffassign](https://github.com/gordonklaus/ineffassign).
+* `gocyclo-check`: Calculates cyclomatic complexities of functions using [gocyclo](https://github.com/fzipp/gocyclo).
+* `static-check`: Analyzes the code for bugs, improvements and more using [staticcheck](https://staticcheck.io/docs/).
+* `gosec-check`: Inspects source code for security problems by scanning the Go AST using the [gosec tool](https://github.com/securego/gosec).
+* `goconst-check`: Finds repeated strings that could be replaced by a constant using [goconst](https://github.com/jgautheron/goconst/).

docs/content/doc/development/structure.md

@@ -0,0 +1,136 @@
+---
+date: "2019-02-12:00:00+02:00"
+title: "Project structure"
+draft: false
+type: "doc"
+menu:
+  sidebar:
+    parent: "development"
+---
+
+# Project structure
+
+In general, this api repo has the following structure:
+
+* `docker`
+* `docs`
+* `pkg`
+  * `caldav`
+  * `config`
+  * `log`
+  * `mail`
+  * `metrics`
+  * `models`
+  * `red`
+  * `routes`
+    * `api/v1`
+  * `swagger`
+  * `utils`
+* `REST-Tests`
+* `templates`
+* `vendor`
+
+This document will explain what these mean and what you can find where.
+
+## Root level
+
+The root directory is where [the config file]({{< ref "../setup/config.md">}}), [Makefile]({{< ref "make.md">}}), license, drone config, 
+application entry point (`main.go`) and so on are located.
+
+## docker
+
+This directory holds additonal files needed to build and run the docker container, mainly service configuration to properly run Vikunja inside a docker 
+container.
+
+## pkg
+
+This is where most of the magic happens. Most packages with actual code are located in this folder.
+
+### caldav
+
+This folder holds a simple caldav implementation which is responsible for returning the caldav feature.
+
+### config
+
+This package configures the config. It sets default values and sets up viper and tells it where to look for config files, 
+how to interpret which env variables for config etc.
+
+If you want to add a new config parameter, you should add default value in this package.
+
+### log
+
+Similar to `config`, this will set up the logging, based on differen logging backends.
+This init is called in `main.go` after the config init is done.
+
+### mail
+
+This package handles all mail sending. To learn how to send a mail, see [sending emails]({{< ref "../practical-instructions/mail.md">}}).
+
+### metrics
+
+This package handles all metrics which are exposed to the prometheus endpoint.
+To learn how it works and how to add new metrics, take a look at [how metrics work]({{< ref "../practical-instructions/metrics.md">}}).
+
+### models
+
+This is where most of the magic happens.
+When adding new features or upgrading existing ones, that most likely happens here.
+
+Because this package is pretty huge, there are several documents and how-to's about it:
+
+* [Adding a feature]({{< ref "../practical-instructions/feature.md">}})
+* [Making calls to the database]({{< ref "../practical-instructions/database.md">}})
+
+### red (redis)
+
+This package initializes a connection to a redis server.
+This inizialization is automatically done at the startup of vikunja.
+
+It also has a function (`GetRedis()`) which returns a redis client object you can then use in your package 
+to talk to redis.
+
+It uses the [go-redis](https://github.com/go-redis/redis) library, please see their configuration on how to use it.
+
+### routes
+
+This package defines all routes which are available for vikunja clients to use.
+To add a new route, see [adding a new route]({{< ref "../practical-instructions/feature.md">}}).
+
+#### api/v1
+
+This is where all http-handler functions for the api are stored. 
+Every handler function which does not use the standard web handler should live here.
+
+### swagger
+
+This is where the [generated]({{< ref "make.md#generate-swagger-definitions-from-code-comments">}} [api docs]({{< ref "../usage/api.md">}}) live. 
+You usually don't need to touch this package.
+
+### utils
+
+A small package, containing some helper functions:
+
+* `MakeRandomString`: Generates a random string of a given length.
+* `Sha256`: Calculates a sha256 hash from a given string.
+
+See their function definitions for instructions on how to use them. 
+
+## REST-Tests
+
+Holds all kinds of test files to directly test the api from inside of [jetbrains ide's](https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html).
+
+These files are currently more an experiment, maybe we will drop them in the future to use something we could integrate in the testing process with drone.
+Therefore, this has no claim to be complete yet even working, you're free to change whatever is needed to get it working for you.
+
+## templates
+
+Holds the email templates used to send plain text and html emails for new user registration and password changes.
+
+## vendor
+
+All libraries needed to build Vikunja. 
+
+We keep all libraries used for Vikunja around in the `vendor/` folder to still be able to build the project even if
+some maintainers take their libraries down like [it happened in the past](https://github.com/jteeuwen/go-bindata/issues/5).
+
+When adding a new  dependency, make sure to run `go mod vendor` to put it inside this directory.

docs/content/doc/development/test.md

@@ -0,0 +1,27 @@
+---
+date: "2019-02-12:00:00+02:00"
+title: "Testing"
+draft: false
+type: "doc"
+menu:
+  sidebar:
+    parent: "development"
+---
+
+# Testing
+
+You can run unit tests with [our `Makefile`]({{< ref "make.md">}}) with
+
+{{< highlight bash >}}
+make test
+{{< /highlight >}}
+
+### Running tests with config
+
+You can run tests with all available config variables if you want, enabeling you to run tests for a lot of scenarios.
+
+To use the normal config set the enviroment variable `VIKUNJA_TESTS_USE_CONFIG=1`.
+
+### Show sql queries
+
+When `UNIT_TESTS_VERBOSE=1` is set, all sql queries will be shown when tests are run.