Skip to content

Commit

Permalink
Provide MkDocs infrastructure (#32)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
rodja and angelom93 authored May 6, 2024
1 parent daf235f commit d47fa8a
Show file tree
Hide file tree
Showing 15 changed files with 517 additions and 59 deletions.
36 changes: 36 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ detector/
*.env
*.swp
site/
docs/reference/
.nicegui/
128 changes: 128 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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.
61 changes: 2 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
85 changes: 85 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
@@ -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!
3 changes: 3 additions & 0 deletions docs/features/field_planner.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Field Planner

The Field Planner is a tool to create and manage fields and routes for the Field Friend.
4 changes: 4 additions & 0 deletions docs/features/user_interface.md
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit d47fa8a

Please sign in to comment.