From 1a4eef1056ec2f7a713066938e7658125568c653 Mon Sep 17 00:00:00 2001 From: kolaente Date: Thu, 3 Sep 2020 17:34:44 +0200 Subject: [PATCH] Add toc to docs --- README.md | 2 +- docs/content/doc/development/db-migrations.md | 2 ++ docs/content/doc/development/development.md | 6 +++-- docs/content/doc/development/mage.md | 2 ++ docs/content/doc/development/migration.md | 14 ++++++----- docs/content/doc/development/structure.md | 2 ++ docs/content/doc/development/test.md | 12 ++++++---- .../doc/practical-instructions/database.md | 6 +++-- .../doc/practical-instructions/mail.md | 6 +++-- .../doc/practical-instructions/metrics.md | 4 +++- .../practical-instructions/swagger-docs.md | 2 +- docs/content/doc/setup/backups.md | 2 ++ .../doc/setup/docker-start-to-finish.md | 2 ++ docs/content/doc/setup/full-docker-example.md | 4 +++- docs/content/doc/setup/install-backend.md | 2 ++ docs/content/doc/setup/install-frontend.md | 2 ++ docs/content/doc/setup/reverse-proxies.md | 2 ++ docs/content/doc/setup/utf-8.md | 12 ++++++---- docs/content/doc/usage/caldav.md | 6 +++-- docs/content/doc/usage/errors.md | 24 ++++++++++--------- docs/content/doc/usage/rights.md | 2 +- docs/themes/vikunja | 2 +- 22 files changed, 77 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 3d07910d..17604156 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ try it on [try.vikunja.io](https://try.vikunja.io)! * [Installing](https://vikunja.io/docs/installing/) * [Build from source](https://vikunja.io/docs/build-from-sources/) * [Development setup](https://vikunja.io/docs/development/) -* [Makefile](https://vikunja.io/docs/makefile/) +* [Magefile](https://vikunja.io/docs/mage/) * [Testing](https://vikunja.io/docs/testing/) All docs can be found on [the vikunja home page](https://vikunja.io/docs/). diff --git a/docs/content/doc/development/db-migrations.md b/docs/content/doc/development/db-migrations.md index 9b574f64..98a24758 100644 --- a/docs/content/doc/development/db-migrations.md +++ b/docs/content/doc/development/db-migrations.md @@ -16,6 +16,8 @@ Additionally, they can also be run directly by using the `migrate` command. We use [xormigrate](https://github.com/techknowlogick/xormigrate) to handle migrations, which is based on gormigrate. +{{< table_of_contents >}} + ## Add a new migration All migrations are stored in `pkg/migrations` and files should have the same name as their id. diff --git a/docs/content/doc/development/development.md b/docs/content/doc/development/development.md index af8eb490..54035bca 100644 --- a/docs/content/doc/development/development.md +++ b/docs/content/doc/development/development.md @@ -17,7 +17,9 @@ 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">}}). +A lot of developing tasks are automated using a Magefile, so make sure to [take a look at it]({{< ref "mage.md">}}). + +{{< table_of_contents >}} ## Libraries @@ -50,7 +52,7 @@ git remote add origin git@git.kolaente.de:/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 +This should provide a working development environment for Vikunja. Take a look at the Magefile to get an overview about the available tasks. The most common tasks should be `mage test:unit` which will start our test environment and `mage build: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. diff --git a/docs/content/doc/development/mage.md b/docs/content/doc/development/mage.md index 6afbe7f4..3601de46 100644 --- a/docs/content/doc/development/mage.md +++ b/docs/content/doc/development/mage.md @@ -15,6 +15,8 @@ Mage is a pure go solution which allows for greater flexibility and things like This document explains what taks are available and what they do. +{{< table_of_contents >}} + ## Installation To use mage, you'll need to install the mage cli. diff --git a/docs/content/doc/development/migration.md b/docs/content/doc/development/migration.md index 8868fe2e..bcd3e6c3 100644 --- a/docs/content/doc/development/migration.md +++ b/docs/content/doc/development/migration.md @@ -16,12 +16,14 @@ To make this easier, we have put together a few helpers which are documented on In general, each migrator implements a migrator interface which is then called from a client. The interface makes it possible to use helper methods which handle http an focus only on the implementation of the migrator itself. -### Structure +{{< table_of_contents >}} + +## Structure All migrator implementations live in their own package in `pkg/modules/migration/`. When creating a new migrator, you should place all related code inside that module. -### Migrator interface +## Migrator interface The migrator interface is defined as follows: @@ -41,7 +43,7 @@ type Migrator interface { } ``` -### Defining http routes +## Defining http routes Once your migrator implements the migration interface, it becomes possible to use the helper http handlers. Their usage is very similar to the [general web handler](https://kolaente.dev/vikunja/web#user-content-defining-routes-using-the-standard-web-handler): @@ -63,7 +65,7 @@ if config.MigrationWunderlistEnable.GetBool() { You should also document the routes with [swagger annotations]({{< ref "../practical-instructions/swagger-docs.md" >}}). -### Insertion helper method +## Insertion helper method There is a method available in the `migration` package which takes a fully nested Vikunja structure and creates it with all relations. This means you start by adding a namespace, then add lists inside of that namespace, then tasks in the lists and so on. @@ -81,7 +83,7 @@ if err != nil { err = migration.InsertFromStructure(fullVikunjaHierachie, user) ``` -### Configuration +## Configuration You should add at least an option to enable or disable the migration. Chances are, you'll need some more options for things like client ID and secret @@ -90,7 +92,7 @@ Chances are, you'll need some more options for things like client ID and secret The easiest way to implement an on/off switch is to check whether your migration service is enabled or not when registering the routes, and then simply don't registering the routes in the case it is disabled. -#### Making the migrator public in `/info` +### Making the migrator public in `/info` You should make your migrator available in the `/info` endpoint so that frontends can display options to enable them or not. To do this, add an entry to `pkg/routes/api/v1/info.go`. diff --git a/docs/content/doc/development/structure.md b/docs/content/doc/development/structure.md index 4e80ddea..675897bb 100644 --- a/docs/content/doc/development/structure.md +++ b/docs/content/doc/development/structure.md @@ -45,6 +45,8 @@ In general, this api repo has the following structure: This document will explain what these mean and what you can find where. +{{< table_of_contents >}} + ## Root level The root directory is where [the config file]({{< ref "../setup/config.md">}}), [Magefile]({{< ref "mage.md">}}), license, drone config, diff --git a/docs/content/doc/development/test.md b/docs/content/doc/development/test.md index 538c4e1f..1ed970be 100644 --- a/docs/content/doc/development/test.md +++ b/docs/content/doc/development/test.md @@ -16,24 +16,26 @@ You can run unit tests with [our `Magefile`]({{< ref "mage.md">}}) with mage test:unit {{< /highlight >}} -### Running tests with config +{{< table_of_contents >}} + +## 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 +## Show sql queries When `UNIT_TESTS_VERBOSE=1` is set, all sql queries will be shown when tests are run. -### Fixtures +## Fixtures All tests are run against a set of db fixtures. These fixtures are defined in `pkg/models/fixtures` in YAML-Files which represent the database structure. When you add a new test case which requires new database entries to test against, update these files. -# Integration tests +## Integration tests All integration tests live in `pkg/integrations`. You can run them by executing `mage test:integration`. @@ -43,7 +45,7 @@ see at the beginning of this document. To run integration tests, use `mage test:integration`. -# Initializing db fixtures when writing tests +## Initializing db fixtures when writing tests All db fixtures for all tests live in the `pkg/db/fixtures/` folder as yaml files. Each file has the same name as the table the fixtures are for. diff --git a/docs/content/doc/practical-instructions/database.md b/docs/content/doc/practical-instructions/database.md index 0ae608eb..6f423148 100644 --- a/docs/content/doc/practical-instructions/database.md +++ b/docs/content/doc/practical-instructions/database.md @@ -18,7 +18,9 @@ This is used whenever you make a call to the database to get or update data. This xorm instance is set up and initialized every time vikunja is started. -### Adding new database tables +{{< table_of_contents >}} + +## Adding new database tables To add a new table to the database, add a an instance of your struct to the `tables` variable in the init function in `pkg/models/models.go`. Xorm will sync them automatically. @@ -27,7 +29,7 @@ You also need to add a pointer to the `tablesWithPointer` slice to enable cachin To learn more about how to configure your struct to create "good" tables, refer to [the xorm documentaion](http://xorm.io/docs/). -### Adding data to test fixtures +## Adding data to test fixtures Adding data for test fixtures is done in via `yaml` files insinde of `pkg/models/fixtures`. diff --git a/docs/content/doc/practical-instructions/mail.md b/docs/content/doc/practical-instructions/mail.md index 1d6671ca..5e7d4c94 100644 --- a/docs/content/doc/practical-instructions/mail.md +++ b/docs/content/doc/practical-instructions/mail.md @@ -12,6 +12,8 @@ menu: This document explains how to use the mailer to send emails and what to do to create a new kind of email to be sent. +{{< table_of_contents >}} + ## Sending emails **Note:** You should use mail templates whenever possible (see below). @@ -30,7 +32,7 @@ type Opts struct { } {{< /highlight >}} -## Sending emails based on a template +### Sending emails based on a template For each mail with a template, there are two email templates: One for plaintext emails, one for html emails. @@ -41,7 +43,7 @@ To send a mail based on a template, use the function `mail.SendMailWithTemplate( `to` and `subject` are pretty much self-explanatory, `tpl` is the name of the template, without `.html.tmpl` or `.plain.tmpl`. `data` is a map you can pass additional data to your template. -#### Sending a mail with a template +### Sending a mail with a template A basic html email template would look like this: diff --git a/docs/content/doc/practical-instructions/metrics.md b/docs/content/doc/practical-instructions/metrics.md index c6e548f1..a05a971f 100644 --- a/docs/content/doc/practical-instructions/metrics.md +++ b/docs/content/doc/practical-instructions/metrics.md @@ -15,6 +15,8 @@ Metrics work by exposing a `/metrics` endpoint which can then be accessed by pro To keep the load on the database minimal, metrics are stored and updated in redis. The `metrics` package provides several functions to create and update metrics. +{{< table_of_contents >}} + ## New metrics First, define a `const` with the metric key in redis. This is done in `pkg/metrics/metrics.go`. @@ -41,6 +43,6 @@ Because metrics are stored in redis, you are responsible to increase or decrease To do this, use `metrics.UpdateCount(value, key)` where `value` is the amount you want to cange it (you can pass negative values to decrease it) and `key` it the redis key used to define the metric. -# Using it +## Using it A Prometheus config with a Grafana template is available at [our git repo](https://git.kolaente.de/vikunja/monitoring). diff --git a/docs/content/doc/practical-instructions/swagger-docs.md b/docs/content/doc/practical-instructions/swagger-docs.md index ad24021d..0ae86db9 100644 --- a/docs/content/doc/practical-instructions/swagger-docs.md +++ b/docs/content/doc/practical-instructions/swagger-docs.md @@ -12,7 +12,7 @@ menu: The api documentation is generated using [swaggo](https://github.com/swaggo/swag) from comments. -### Documenting structs +## Documenting structs You should always comment every field which will be exposed as a json in the api. These comments will show up in the documentation, it'll make it easier for developers using the api. diff --git a/docs/content/doc/setup/backups.md b/docs/content/doc/setup/backups.md index 0dbf1cfb..b901dd68 100644 --- a/docs/content/doc/setup/backups.md +++ b/docs/content/doc/setup/backups.md @@ -13,6 +13,8 @@ menu: Vikunja does not store any data outside of the database. So, all you need to backup are the contents of that database and maybe the config file. +{{< table_of_contents >}} + ## MySQL To create a backup from mysql use the `mysqldump` command: diff --git a/docs/content/doc/setup/docker-start-to-finish.md b/docs/content/doc/setup/docker-start-to-finish.md index f7de6782..d56049db 100644 --- a/docs/content/doc/setup/docker-start-to-finish.md +++ b/docs/content/doc/setup/docker-start-to-finish.md @@ -17,6 +17,8 @@ We'll use [docker compose](https://docs.docker.com/compose/) to make handling th > If you have any issues setting up vikunja, please don't hesitate to reach out to us via [matrix](https://riot.im/app/#/room/!dCRiCiLaCCFVNlDnYs:matrix.org?via=matrix.org), the [community forum](https://community.vikunja.io/) or even [email](mailto:hello@vikunja.io). +{{< table_of_contents >}} + ## Preparations (optional) Create a directory for the project where all data and the compose file will live in. diff --git a/docs/content/doc/setup/full-docker-example.md b/docs/content/doc/setup/full-docker-example.md index 00612e66..9e67c321 100644 --- a/docs/content/doc/setup/full-docker-example.md +++ b/docs/content/doc/setup/full-docker-example.md @@ -21,7 +21,9 @@ For all available configuration options, see [configuration]({{< ref "config.md" All examples on this page already reflect this and do not require additional work. -### Redis +{{< table_of_contents >}} + +## Redis To use redis, you'll need to add this to the config examples below: diff --git a/docs/content/doc/setup/install-backend.md b/docs/content/doc/setup/install-backend.md index 3e5507ce..f395c97f 100644 --- a/docs/content/doc/setup/install-backend.md +++ b/docs/content/doc/setup/install-backend.md @@ -15,6 +15,8 @@ menu: }}">make sure your db is utf-8 compatible. +{{< table_of_contents >}} + ## Install from binary Download a copy of Vikunja from the [download page](https://vikunja.io/en/download/) for your architecture. diff --git a/docs/content/doc/setup/install-frontend.md b/docs/content/doc/setup/install-frontend.md index ea9cbe4f..2989b643 100644 --- a/docs/content/doc/setup/install-frontend.md +++ b/docs/content/doc/setup/install-frontend.md @@ -17,6 +17,8 @@ Unzip them and store them somewhere your server can access them. You also need to configure a rewrite condition to internally redirect all requests to `index.html` which handles all urls. +{{< table_of_contents >}} + ## API URL configuration By default, the frontend assumes it can reach the api at `/api/v1` relative to the frontend url. diff --git a/docs/content/doc/setup/reverse-proxies.md b/docs/content/doc/setup/reverse-proxies.md index 7ab5f2f0..3d78c71f 100644 --- a/docs/content/doc/setup/reverse-proxies.md +++ b/docs/content/doc/setup/reverse-proxies.md @@ -13,6 +13,8 @@ menu: These examples assume you have an instance of the backend running on your server listening on port `3456`. If you've changed this setting, you need to update the server configurations accordingly. +{{< table_of_contents >}} + ## NGINX Below are two example configurations which you can put in your `nginx.conf`: diff --git a/docs/content/doc/setup/utf-8.md b/docs/content/doc/setup/utf-8.md index 8c6abf07..796fa529 100644 --- a/docs/content/doc/setup/utf-8.md +++ b/docs/content/doc/setup/utf-8.md @@ -17,6 +17,8 @@ Vikunja itself will work just fine until you want to use non-latin characters in On this page, you will find information about how to fully ensure non-latin characters like aüäß or emojis work with your installation. +{{< table_of_contents >}} + ## Postgresql & SQLite Postgresql and SQLite should handle utf-8 just fine - If you discover any issues nonetheless, please @@ -49,11 +51,11 @@ The charset `latin1` means the db is encoded in the `latin1` encoding which does (The following guide is based on [this thread from stackoverflow](https://dba.stackexchange.com/a/104866)) -#### 0. Backup your database +### 0. Backup your database Before attempting any conversion, please [back up your database]({{< ref "backups.md">}}). -#### 1. Create a pre-conversion script +### 1. Create a pre-conversion script Copy the following sql statements in a file called `preAlterTables.sql` and replace all occurences of `vikunja` with the name of your database: @@ -70,7 +72,7 @@ SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name, "` CHANGE `",column FROM `COLUMNS` where table_schema like 'vikunja' and data_type in ('text','tinytext','mediumtext','longtext'); {{< /highlight >}} -#### 2. Run the pre-conversion script +### 2. Run the pre-conversion script Running this will create the actual migration script for your particular database structure and save it in a file called `alterTables.sql`: @@ -78,7 +80,7 @@ Running this will create the actual migration script for your particular databas mysql -uroot < preAlterTables.sql | egrep '^ALTER' > alterTables.sql {{< /highlight >}} -#### 3. Convert the database +### 3. Convert the database At this point converting is just a matter of executing the previously generated sql script: @@ -86,7 +88,7 @@ At this point converting is just a matter of executing the previously generated mysql -uroot < alterTables.sql {{< /highlight >}} -#### 4. Verify it was successfully converted +### 4. Verify it was successfully converted If everything worked as intended, your db collation should now look like this: diff --git a/docs/content/doc/usage/caldav.md b/docs/content/doc/usage/caldav.md index bb0e7d6a..72274116 100644 --- a/docs/content/doc/usage/caldav.md +++ b/docs/content/doc/usage/caldav.md @@ -16,6 +16,8 @@ menu: Vikunja supports managing tasks via the [caldav VTODO](https://tools.ietf.org/html/rfc5545#section-3.6.2) extension. +{{< table_of_contents >}} + ## URLs All urls are located under the `/dav` subspace. @@ -64,11 +66,11 @@ Vikunja **currently does not** support these properties: ## Tested Clients -#### Working +### Working * [Evolution](https://wiki.gnome.org/Apps/Evolution/) -#### Not working +### Not working * [Tasks (Android)](https://tasks.org/) diff --git a/docs/content/doc/usage/errors.md b/docs/content/doc/usage/errors.md index f64cb68c..4c308aed 100644 --- a/docs/content/doc/usage/errors.md +++ b/docs/content/doc/usage/errors.md @@ -12,13 +12,15 @@ menu: This document describes the different errors Vikunja can return. -### Generic +{{< table_of_contents >}} + +## Generic | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| | 0001 | 403 | Generic forbidden error. | -### User +## User | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -39,14 +41,14 @@ This document describes the different errors Vikunja can return. | 1017 | 412 | The provided Totp passcode is invalid. | | 1018 | 412 | The provided user avatar provider type setting is invalid. | -### Validation +## Validation | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| | 2001 | 400 | ID cannot be empty or 0. | | 2002 | 400 | Some of the request data was invalid. The response contains an aditional array with all invalid fields. | -### List +## List | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -57,7 +59,7 @@ This document describes the different errors Vikunja can return. | 3007 | 400 | A list with this identifier already exists. | | 3008 | 412 | The list is archived and can therefore only be accessed read only. This is also true for all tasks associated with this list. | -### Task +## Task | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -81,7 +83,7 @@ This document describes the different errors Vikunja can return. | 4018 | 403 | Invalid task filter concatinator. | | 4019 | 403 | Invalid task filter value. | -### Namespace +## Namespace | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -93,7 +95,7 @@ This document describes the different errors Vikunja can return. | 5011 | 409 | This user has already access to that namespace. | | 5012 | 412 | The namespace is archived and can therefore only be accessed read only. | -### Team +## Team | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -104,14 +106,14 @@ This document describes the different errors Vikunja can return. | 6006 | 400 | Cannot delete the last team member. | | 6007 | 403 | The team does not have access to the list to perform that action. | -### User List Access +## User List Access | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| | 7002 | 409 | The user already has access to that list. | | 7003 | 403 | The user does not have access to that list. | -### Label +## Label | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| @@ -119,13 +121,13 @@ This document describes the different errors Vikunja can return. | 8002 | 404 | The label does not exist. | | 8003 | 403 | The user does not have access to this label. | -### Right +## Right | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| | 9001 | 403 | The right is invalid. | -### Kanban +## Kanban | ErrorCode | HTTP Status Code | Description | |-----------|------------------|-------------| diff --git a/docs/content/doc/usage/rights.md b/docs/content/doc/usage/rights.md index 0eb34185..726ec83e 100644 --- a/docs/content/doc/usage/rights.md +++ b/docs/content/doc/usage/rights.md @@ -23,7 +23,7 @@ The following values are possible: | 1 | Read and write. Namespaces or lists shared with this right can be read and written to by the team or user. | | 2 | Admin. Can do anything like read and write, but can additionally manage sharing options. | -### Team admins +## Team admins When adding or querying a team, every member has an additional boolean value stating if it is admin or not. A team admin can also add and remove team members and also change whether a user in the team is admin or not. \ No newline at end of file diff --git a/docs/themes/vikunja b/docs/themes/vikunja index a17ba597..958219fc 160000 --- a/docs/themes/vikunja +++ b/docs/themes/vikunja @@ -1 +1 @@ -Subproject commit a17ba5976906ee431943798c08e4d3c38689590d +Subproject commit 958219fc84db455ed58d7a4380bbffc8d04fd5cf