My Workshop

A documentation generator for open hardware projects.

This project is currently unmaintained.

Features

• Generate beautiful documentation for open hardware projects!

Installation

Requirements

• Docker: we use Docker to develop and run My Workshop. This is a strict requirement to use this project.
• Docker Compose: we use Docker Compose to simplify the orchestration of all My Workshop application services, using configuration files for different environments (such as dev, test, staging or prod).

Download this repository and unzip it on your computer. You should rename the folder myworkshop-master in myworkshop.

Or clone the repository directly on your computer:

$ git clone git@github.com:myworkshopproject/myworkshop.git

Install and run a production environment

My Workshop stores config in environment variables. You must set these environment variables before running My Workshop, either directly or by providing the file .env. To make things easier, we have prepared the .env.example template that you can adapt to your project.

Once the environment variables are set, you can build and start all the services of the My Workshop application (via Docker Compose) using the following command:

$ make prod

You can now access the application with your favorite internet browser at the address you set in the $DOMAIN environment variable.

When launching the application for the first time, you will need to create a super user to manage it. You can do this using the following command:

$ docker exec -it myworkshop_core_1 make createsuperuser

Finally, To stop all application services, use the following command:

$ make stop

Install and run a development environment

You can build and start a development environment (completely independent of the production one) with the following command:

$ make dev

This previous command builds all the required services for development and starts them all except the core web server and workers.

To start the Django web server, please open a terminal in the container:

$ docker exec -it myworkshop-dev_core_1 /bin/bash

Then run:

$ make venv
$ make install
$ make migrate
$ make populate-db
$ make createsuperuser
$ make serve-dev

To start a Celery worker, please run:

$ docker exec -it myworkshop-dev_core_1 make worker

To start the frontend dev environment, please open a terminal in the container:

$ docker exec -it myworkshop-dev_frontend_1 /bin/bash

Then run:

$ npm install
$ npm run build

Tech/framework used

• NGINX: a free and open-source web server used as a reverse proxy;
• Django: a Python-based free and open-source web framework;
• PostgreSQL: a free and open-source relational database management system.

Contributing

For the sake of simplicity, to ease interaction with the community, we use the GitHub flow for open-source projects. In a few words:

• The master branch is always stable and deployable;
• Tags from the master branch are considered as releases;
• Contributors have to fork or create a new feature-branch to work on (if they are allowed to in the original repository) and propose a pull request to merge their branch to master.

If you'd like to contribute, please raise an issue or fork the repository and use a feature branch. Pull requests are warmly welcome!

Versioning

We use SemVer for versioning. See the CHANGELOG.md file for details.

Licensing

The code in this project is licensed under MIT license. See the LICENSE file for details.

Contributors

• Julien Lebunetel - jlebunetel.