Skip to content

Commit 2add378

Browse files
lutangarlutangar
authored
docs: makes the main README shinier ✨ (#331)
* doc: make the main README shinier ✨ Add some more descriptions for human beings and robots. Simplify instruction for developers and dispatch some info to other specifics README. *Since __DatAtlas__ is a monorepo it could live in the __Erasme__ __Github__ org if we wanted to.*$ * chore: update README.md * docs: style * docs: style --------- Co-authored-by: lutangar <[email protected]>
1 parent eff1bf4 commit 2add378

File tree

2 files changed

+85
-74
lines changed

2 files changed

+85
-74
lines changed

‎README.md‎

Lines changed: 62 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,48 @@
11
# Datatlas
22

3-
## Getting started
3+
🌍 **DatAtlas** is a geospatial data vizualization tool ✨ based on **Kepler.gl** and developed by [**Erasme**](https://www.erasme.org), the open innovation lab of the **Lyon** 🇫🇷 metropolitan area.
44

5-
### Locally
5+
**DatAtlas** allows to create and share custom interactive maps from various datasource:
66

7-
```
8-
npm install
9-
cp .env.example .env
10-
```
7+
1. Name your map and choose your favorite map style 💅
8+
2. Import datasources from files or URLS in `GeoJson`, `csv`, etc.
9+
3. Customize the UI for your visitors ✨
10+
4. Publish and share your map with the world! 🌍
1111

12-
### Using **Docker**
12+
![A 3D map of the industries around Lyon and Saint-Etienne. It represents the number of industry on a territory using clusters displayed as 3D stacked histograms. This map was created with DatAtlas.](https://user-images.githubusercontent.com/33604381/183027634-6bb76d0f-cb53-412c-93cb-2af5acb290e4.png)
1313

14-
```
14+
## Under the hood
15+
16+
**DatAtlas** is a custom **Kepler.gl** frontend with a **Nestjs** API allowing to save and share your maps via a URL.
17+
18+
**Kepler.gl** is an open-source, data-agnostic, high-performance app for visual exploration of large-scale geolocation data sets. It's built on top of [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) and [DECK.gl](https://deck.gl/).
19+
It can render **millions** of points representing thousands of trips and perform spatial aggregations on the fly.
20+
21+
**DatAtlas** fix some of **Kepler.gl** issues to allow multiple maps to work flawlessly in a single app.
22+
23+
It also brings documentation on some hidden customization features and shed some light on some of the complex patterns used in the **Kepler.gl** codebase.
24+
25+
> _Support our contributions to the **Kepler.gl** codebase!_ > https://github.com/keplergl/kepler.gl/issues?q=is%3Aopen+author%3Alutangar
26+
27+
## Getting started
28+
29+
```sh
30+
npm install
1531
cp .env.example .env
1632
docker compose up
17-
nx run-many --target=serve
33+
npx nx serve backend
34+
npx nx serve frontend
1835
```
1936

37+
> Or both:
38+
>
39+
> ```sh
40+
> npx nx run-many --target=serve
41+
> ```
42+
43+
It opens a new tab at http://localhost:3000/.
44+
The app will automatically reload if you change any of the source files.
45+
2046
> **Note**: you must manually configure `pgadmin` :
2147
>
2248
> 1. Right-click _Servers > Register > Server..._
@@ -29,38 +55,38 @@ nx run-many --target=serve
2955
>
3056
> https://towardsdatascience.com/how-to-run-postgresql-and-pgadmin-using-docker-3a6a8ae918b5
3157
32-
**Setup app `.env` :**
58+
### Frontend
3359
34-
> See **app** [./apps/frontend/README.md](./apps/frontend/README.md).
60+
> See **app** [./apps/frontend/README.md](./apps/frontend/README.md)
3561
36-
## Development
62+
### Backend
3763
38-
### Code quality
64+
> See **API** [./apps/backend/README.md](./apps/backend/README.md)
3965
40-
Run `prettier` on whole repository:
66+
## Development
4167
42-
```
43-
nx format:write
44-
```
68+
> Visit the [Nx Documentation](https://nx.dev) to learn more.
4569
46-
Run `lint` on whole repository
70+
### Code quality
4771
48-
```
49-
nx run-many --target=lint
72+
Run both `prettier` and `eslint`:
73+
74+
```sh
75+
npx nx format:write --base=origin/dev && npx nx run-many --target=lint --base=origin/dev
5076
```
5177
52-
### Update dependencies
78+
### Bulk dependencies updates
5379
54-
For example update `nestjs` :
80+
To update `nestjs` and keep in sync all side packages:
5581
56-
```shell
82+
```sh
5783
npx npm-check-updates --filter "@nestjs/*" -u
5884
```
5985
60-
Or to update `mikro-orm` :
86+
Or to update `mikro-orm` and friends:
6187
62-
```
63-
npx npm-check-updates --filter "@mikro-orm/*" -u
88+
```sh
89+
npx npm-check-updates --filter "@mikro-orm/*" -
6490
```
6591
6692
### Database migrations
@@ -74,63 +100,25 @@ npm run mikro-orm migration:up
74100
75101
Run a single test file:
76102
77-
```
103+
```sh
78104
npx nx run backend-e2e:e2e --spec apps/backend-e2e/src/e2e/user.cy.ts
79105
```
80106
81-
https://github.com/cypress-io/cypress/issues/2610#issuecomment-1319738814
107+
> See https://github.com/cypress-io/cypress/issues/2610#issuecomment-1319738814
82108
83-
Output test results to a log file:
109+
Output test results to a log file for debugging purpose:
84110
85-
```
111+
```sh
86112
npx nx run backend-e2e:e2e --spec apps/backend-e2e/src/e2e/user.cy.ts &> cypress.log
87113
```
88114
89-
#### Cypress
90-
91-
https://github.com/nrwl/nx/tree/master/packages/cypress/docs
92-
93-
### Backend
94-
95-
```
96-
nx serve backend
97-
```
98-
99-
> Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
100-
101-
#### Swagger
102-
103-
You can reach swagger and see all the API routes at http://localhost:3333/api/
104-
105-
Please note that most routes require an authentication. Reach it out via this route `/api/auth/login` and
106-
sending this body :
107-
108-
```json
109-
{
110-
"email": "your_email",
111-
"password": "your-password"
112-
}
113-
```
114-
115-
Those credentials are the one you should have put in your `.env` file.
116-
117-
## Design
118-
119-
**Figma** sketch :
120-
`https://www.figma.com/proto/lVX7Lycox3AGixBhhbhQsQ/DatAtlas`
121-
122-
> _Made by [SiaPartners](https://www.sia-partners.com/)._
123-
124-
## nx
125-
126-
<a href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
127-
128-
✨ **This workspace has been generated by [Nx, a Smart, fast and extensible build system.](https://nx.dev)** ✨
115+
> See **Cypress** documentation :
116+
> https://github.com/nrwl/nx/tree/master/packages/cypress/docs
129117
130-
### Understand this workspace
118+
## Credits
131119
132-
Run `nx graph` to see a diagram of the dependencies of the projects.
120+
**DatAtlas** was created by [**Erasme**](https://www.erasme.org), the open innovation lab of Lyon 🇫🇷 metropolitan area. It's a part of the larger [**DatAgora**](https://www.erasme.org/DatAgora) initiative.
133121
134-
### Further help
122+
This project was supported by the [**France Relance**](https://www.economie.gouv.fr/plan-de-relance) economic recovery plan.
135123
136-
Visit the [Nx Documentation](https://nx.dev) to learn more.
124+
[**Figma** sketch](https://www.figma.com/proto/lVX7Lycox3AGixBhhbhQsQ/DatAtlas) was made by [SiaPartners](https://www.sia-partners.com/).

‎apps/backend/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# DatAtlas API
2+
3+
## Getting started
4+
5+
```
6+
nx serve backend
7+
```
8+
9+
## Open API documentation (formerly known as **Swagger**)
10+
11+
The documentation is reachable at http://localhost:3333/api/
12+
13+
Please note that most routes require an authentication.
14+
Reach it out via this route `/api/auth/login` and sending the following payload :
15+
16+
```json
17+
{
18+
"email": "[email protected]",
19+
"password": "admin"
20+
}
21+
```
22+
23+
> _Credentials are the one in your `.env` file._

0 commit comments

Comments
 (0)