# Document Funkwhale

```{tip}
If you notice something missing in our documentation but don't feel confident contributing, submit a request [in our forum](https://forum.funkwhale.audio/t/documentation).
```

We try to document Funkwhale as thoroughly as possible to make it easy for users, admins, developers, and contributors to understand how everything works.

```{contents}
:local:
```

## Requirements

To work on Funkwhale's documentation, you need the following:

- [Git](https://git-scm.com): our version control system
- [Poetry](https://python-poetry.org/): A python packaging tool and dependency manager
- A text editor of your choice

## Tooling

We use [Sphinx](https://www.sphinx-doc.org/) to generate our documentation. Sphinx provides excellent tooling for documenting Python projects. We write documentation in Markdown using the [MyST parser](https://myst-parser.readthedocs.io/en/latest/) to access Sphinx's features.

All documentation in Funkwhale is stored in the [main Funkwhale Git repository](https://dev.funkwhale.audio/funkwhale/funkwhale/-/tree/develop/docs).

## Style guide

We broadly follow the [Microsoft writing style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for language and tone. You should aim to keep your language simple and clear enough for readers of all levels. You can use a free tool like [Hemingway](https://hemingwayapp.com) to check the complexity of your sentences.

Here are some basic rules to follow:

1. Write in American English
2. Always use sentence casing for headers. For example: "Contribute to Funkwhale documentation" rather than "Contribute To Funkwhale Documentation"
3. Use contractions such as "don't" and "can't" to make your writing feel conversational. Only use the full words if you're trying to emphasize something

## Local setup

We provide a fully automated setup for a local live-preview of your changes. Make sure you meet the requirements outlined above and run `make dev`.

A real-time preview of the documentation is available on `http://0.0.0.1:8001`

## Redirects

If you move content to a new location, you need to set up a redirect. This ensures that any bookmarks or links posted before the change still take the user where they expect to go.

All redirects are stored in a {file}`redirects.txt` file. This is a simple text file containing one redirect per line. Each line contains the old URL and new URL as relative URLs.

In this example, the `architecture.html` file redirects to `https://docs.funkwhale.audio/developers/architecture.html`.

```{code-block} text
architecture.html, developers/architecture.html
```

## Contribution flow

Here's an example of the typical workflow for creating documentation:

1. [Create a fork](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) of the Funkwhale codebase
2. Create a new branch for your documentation. In this example `my-branch-name` is the name of the branch

   ```{code-block} sh
   git checkout -b my-branch-name
   ```

3. Make your changes and verify them by running the [Docker container](#local-setup)
4. Add [redirects](#redirects) if required
5. Add a [changelog fragment](../developer/workflows/changelog.md)
6. Add your changed files to a commit

   ```{code-block} sh
   git add . # Add all changed files
   git add doc1.md doc2.md # Add specific files
   ```

7. Create a commit with a meaningful commit message

   ```{code-block} sh
   git commit -m "A meaningful commit message"
   ```

8. Push your changes to your fork

   ```{code-block} sh
   git push origin my-branch-name
   ```

9. Create a merge request in the [main Funkwhale repository](https://dev.funkwhale.audio/funkwhale/funkwhale)
