Provide MkDocs infrastructure (#32)

* created basic mkdocs structure

* generate reference

* add forgotten file

* first step to publish docs automatically

* build reference

* add rosys requirement to generate reference

* install all requirements

* just skip import errors

* cleanup

* debugging docs build

* use mkdocs 1.5.3

* fix

* improved wording

---------

Co-authored-by: Miguel Belo <[email protected]>

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Upload Python Package
+
+on: push
+
+# on:
+#   workflow_dispatch:
+#   push:
+#     tags:
+#       - v**
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python3 -m pip install -r requirements.txt
+          python3 -m pip install -r mkdocs_requirements.txt
+          python3 -m pip install -e .
+      - name: Build docs
+        run: mkdocs build -v
+      - name: Analyze
+        run: |
+          pwd
+          ls -lha
+      - name: Deploy gh-pages
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: site

.gitignore

@@ -6,4 +6,5 @@ detector/
 *.env
 *.swp
 site/
+docs/reference/
 .nicegui/

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

README.md

@@ -2,65 +2,8 @@
 
 # Zauberzeug Field Friend
 
-This is the full source code of the [Field Friend](http://feldfreund.de) (aka Feldfreund) weeding robot.
+This is the full source code of the [Field Friend](http://feldfreund.de) (aka Feldfreund) agricultural robot.
 The software is based on [RoSys](https://rosys.io) and fully Open Source.
 The hardware is build by [Zauberzeug](http://zauberzeug.com) and intended as a platform to advance organic and regenerative agriculture.
 
-## Features
-
-- full control via web interface
-- manual steering with touch-joystick and keyboard
-- camera/motor calibration for real world coordinate system (unit: meters)
-- ...
-
-## Getting Started
-
-Run these commands on your local machine to start the Field Friend simulation:
-
-```bash
-git clone [email protected]:zauberzeug/field_friend.git
-cd field_friend
-python3 -m pip install -r requirements.txt
-./main.py
-```
-
-This will open the user interface with a simulated robot in your browser.
-
-NOTE: The software is intended to run on Linux and Unix systems.
-If you are using windows please consider running in a Docker container or virtual machine.
-
-## On Real Hardware
-
-### Development
-
-The following instructions will only work if you have a real "Zauberzeug Field Friend" at your disposal.
-Contact [[email protected]](mailto:[email protected]) if you are interested in a non-profit purchase of this development hardware.
-
-#### Setup
-
-1. ensure you can login via ssh without providing a password (via `ssh-copy-id` command)
-2. ensure you have [LiveSync](https://github.com/zauberzeug/livesync) installed with <br> `python3 -m pip install livesync`
-3. ensure the latest version of the docker image is installed on the Field Friend by syncing the code as described below and then running <br> `./docker.sh uppull`
-4. Optional: ensure the correct docker containers are loaded on startup by running <br> `./docker.sh stopall && ./docker.sh uppull && ./docker.sh install`
-5. Optional: update the [Lizard](https://lizard.dev) microcontroller firmware on your Robot Brain by accessing the Field Friend web interface and navigating to the "Developer" options
-
-#### Deploy and Change Code
-
-1. go to your local `field_friend` folder and start the [LiveSync](https://github.com/zauberzeug/livesync) script: <br>
-   `./sync.py <ssh-host-name-of-field-friend>`
-2. this will deploy your local code to the Field Friend
-3. as long as [LiveSync](https://github.com/zauberzeug/livesync) is active, all code change are automatically pushed to the machine
-4. any code changes will automatically trigger a reload on the Field Friend
-
-### Update RoSys and NiceGUI
-
-To utilize personal versions of RoSys and NiceGUI instead of the default ones provided in the docker image,
-modify the `sync.py` file by uncommenting the specific folders.
-
-### Debugging
-
-You can see the current log with
-
-```bash
-./docker.sh l rosys
-```
+Please see the [documentation](https://docs.feldfreund.de) for details on installation, setup and usage.

docs/contributing.md

@@ -0,0 +1,85 @@
+# Contributing
+
+We're thrilled that you're interested in contributing to the Field Friend source code!
+Here are some guidelines that will help you get started.
+
+## Reporting issues
+
+If you encounter a bug or other issue, the best way to report it is by opening a new issue on our [GitHub repository](https://github.com/zauberzeug/field_friend).
+When creating the issue, please provide a clear and concise description of the problem, including any relevant error messages and code snippets.
+If possible, include steps to reproduce the issue.
+
+## Code of Conduct
+
+We follow a [Code of Conduct](https://github.com/zauberzeug/field_friend/blob/main/CODE_OF_CONDUCT.md) to ensure that everyone who participates in the NiceGUI community feels welcome and safe.
+By participating, you agree to abide by its terms.
+
+## Contributing code
+
+We are excited that you want to contribute code to the Field Friend source code.
+We're always looking for bug fixes, performance improvements, and new features.
+
+## Coding Style Guide
+
+### Formatting
+
+We use [autopep8](https://github.com/hhatto/autopep8) with a 120 character line length to format our code.
+Before submitting a pull request, please run
+
+```bash
+autopep8 --max-line-length=120 --in-place --recursive .
+```
+
+on your code to ensure that it meets our formatting guidelines.
+Alternatively you can use VSCode, open the field_friend.code-workspace file and install the recommended extensions.
+Then the formatting rules are applied whenever you save a file.
+
+In our point of view, the Black formatter is sometimes a bit too strict.
+There are cases where one or the other arrangement of, e.g., function arguments is more readable than the other.
+Then we like the flexibility to either put all arguments on separate lines or only put the lengthy event handler
+on a second line and leave the other arguments as they are.
+
+### Imports
+
+We use [ruff](https://docs.astral.sh/ruff/) to automatically sort imports:
+
+```bash
+ruff check . --fix
+```
+
+### Single vs Double Quotes
+
+Regarding single or double quotes: [PEP 8](https://peps.python.org/pep-0008/) doesn't give any recommendation, so we simply chose single quotes and sticked with it.
+On qwerty keyboards it's a bit easier to type, is visually less cluttered, and it works well for strings containing double quotes from the English language.
+
+### F-Strings
+
+We use f-strings where ever possible because they are generally more readable - once you get used to them.
+There are only a few places in the code base where performance really matters and f-strings might not be the best choice.
+These places should be marked with a `# NOTE: ...` comment when diverging from f-string usage.
+
+## Documentation
+
+### Formatting
+
+Because it has [numerous benefits](https://nick.groenen.me/notes/one-sentence-per-line/) we write each sentence in a new line.
+
+### Examples
+
+Each example should be about one concept.
+Please try to make them as minimal as possible to show what is needed to get some kind of functionality.
+We are happy to merge pull requests with new examples which show new concepts, ideas or interesting use cases.
+
+## Pull requests
+
+To get started, fork the repository on GitHub, clone it somewhere on your filesystem, commit and push your changes,
+and then open a pull request (PR) with a detailed description of the changes you've made
+(the PR button is shown on the GitHub website of your forked repository).
+
+When submitting a PR, please make sure that the code follows the existing coding style and that all tests are passing.
+If you're adding a new feature, please include tests that cover the new functionality.
+
+## Thank you!
+
+Thank you for your interest in contributing.
+We're looking forward to work with you!

docs/features/field_planner.md

@@ -0,0 +1,3 @@
+# Field Planner
+
+The Field Planner is a tool to create and manage fields and routes for the Field Friend.

docs/features/user_interface.md

@@ -0,0 +1,4 @@
+# User Interface
+
+The Field Friend user interface is a web application build with [NiceGUI](https://nicegui.io).
+This allows you to control the robot via the local "Feldfreund" WiFi hotspot or remotely via NiceGUI On Air.