Skip to content

doc: create centralized documentation for developers #1120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,6 @@ dist/
# Local Netlify folder
.netlify
src/emulator/release/

# Dinamic dev documentation files
doc/dev_doc/site
17 changes: 1 addition & 16 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,4 @@ to ask questions.

## Contributor Documentation

### Where to Start

Start with [Repo Structure and Tooling](./contributors/structure.md).

### Index

- **Conventions**
- [Repo Structure and Tooling](./contributors/structure.md)
- How directories and files are organized in our GitHub repo
- What tools are used to build parts of Puter
- [Comment Prefixes](./contributors/comment_prefixes.md)
- A convention we use for line comments in code

- [Frontend Documentation](/src/gui/doc)
- [Backend Documentation](/src/backend/doc)
- [Extensions](./contributors/extensions/)
Interested in contributing? [Find all documentation for Puter's contributors here.](./contributors/README.md)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm okay with keeping a few redundant links here for easy-of-access.

Suggested change
Interested in contributing? [Find all documentation for Puter's contributors here.](./contributors/README.md)
Interested in contributing? Check out the resources below:
- [Contributor Documentation](./contributors/README.md)
- [Frontend Documentation](/src/gui/doc)
- [Backend Documentation](/src/backend/doc)

38 changes: 38 additions & 0 deletions doc/contributors/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Contributors-oriented documentation

## Where to Start

Start with [Repo Structure and Tooling](./contributors/structure.md).

### Index

- **Conventions**
- [Repo Structure and Tooling](./structure.md)
- How directories and files are organized in our GitHub repo
- What tools are used to build parts of Puter
- [Comment Prefixes](./comment_prefixes.md)
- A convention we use for line comments in code

- [Frontend Documentation](../../src/gui/doc/)
- [Backend Documentation](../../src/backend/doc/README.md)
- [Extensions](./extensions/README.md)

## How to find documentation on something

You will be able to find existing documentation on a contribution topic **following the structure** of the contributor documentation.
[`This is the structure`](./structure.md) of puter's contributors-oriented docs.

## How to understand the code and work of others more easily

**Comments** are used in code to make them easier to read.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The statement about what comments are for is unnecessary, but this would be a good place to describe effective ways to use comments.

Suggested change
**Comments** are used in code to make them easier to read.
**Comments** should supplement the code. Instead of describing what the code does, describe the code's purpose or contextual information that makes it easier to understand.


Also, comments uses prefixes for improve their clearness.
[`Here you will find the standard`](./comment_prefixes.md) that is followed.

## How to interact with the puter team and other contributors

[`Here you will find our colaboration guidelines`](./oscon.md) so you can get started.

## Get support

Keep in touch [by using these means of contact](./support.md)
41 changes: 41 additions & 0 deletions doc/contributors/contribute_on_docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# This documentation

## About

This documentation tries to gather in an easy to navigate place for a developer (no matter his area of work, it can be frontend, backend, devops, etc...) the documentation related to the development of the opensource Puter project.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should avoid gendered language here.

Suggested change
This documentation tries to gather in an easy to navigate place for a developer (no matter his area of work, it can be frontend, backend, devops, etc...) the documentation related to the development of the opensource Puter project.
This documentation tries to gather in an easy to navigate place for a developer (no matter their area of work, it can be frontend, backend, devops, etc...) the documentation related to the development of the opensource Puter project.


General documentation is located in the ‘doc/’ directory while specific documentation is kept in the directories closest to what it documents.

Documentation runs on mkdocs tool, an easy and powerful documentation tool written in Python. It was decided to use this tool since most of the existing documentation was in markdown format, and seeing that new contributors were also adding new documentation in markdown format.

## Documentation in the repository

The documentation can be accessed through [the official project repository Wiki](https://github.com/HeyPuter/puter/wiki). This is since commit 99684d8.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will github automatically link this commit hash? If it doesn't, we should make it a link in case people are curious about going through the git history.


## Get started with docs

1. Clone puter's repo.
2. Install mkdocs and mkdocs-material.
```
pip install mkdocs && pip install mkdocs-material
```
3. Navigate to the doc/ directory.
4. Build the documentation
```
mkdocs build && mkdocs serve
```
5. Now you should have it live on the IP http://127.0.0.1:8000

In the ```doc/``` directory you will find all the source files of the documentation in markdown format. You can edit them and create new ones under that directory, and incorporate them into the documentation either using the navbar of the documentation (see the doc/dev_doc/mkdocs.yml file) or using internal links with markdown.

---

Using mkdocs you can install themes. For this documentation, you will need to install material theme:

```
pip install mkdocs-material
```

---

If you find any bug or error in this documentation, do not hesitate to send your complaint to **[email protected]**, or **colaborate** with the documentation yourself.
7 changes: 7 additions & 0 deletions doc/contributors/guides/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Dev guides

This is a collection of development guides that follow the practices, tools and conventions of the project.

1. [How to make a driver.](./how_to_make_driver.md)
> There is also a [video from Eric on this](https://www.youtube.com/watch?v=8znQmrKgNxA)
2. [Passing arguments to phoenix shell](https://www.youtube.com/watch?v=VDPu7hwBsq8)
Loading