forked from Ivasoft/geovisio-website
Add mkdocs config
This commit is contained in:
Adrien Pavie
6
.gitignore
vendored
6
.gitignore
vendored
@@ -93,4 +93,8 @@ sw.*
|
||||
cypress/downloads/*
|
||||
cypress/screenshot/
|
||||
cypress/videos/
|
||||
*.cy.ts.mp4
|
||||
*.cy.ts.mp4
|
||||
|
||||
# Mkdocs
|
||||
env/
|
||||
site/
|
||||
|
||||
@@ -1,29 +0,0 @@
|
||||
# GeoVisio Website hands-on guide
|
||||
|
||||
|
||||
|
||||
Welcome to GeoVisio __Website__ documentation ! It will help you through all phases of setup, run and develop on GeoVisio Website.
|
||||
|
||||
__Note that__ this only covers the Website / front-end component, if you're looking for docs on another component, you may go to [this page](https://gitlab.com/panoramax) instead.
|
||||
|
||||
Also, if at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/panoramax/server/website/-/issues) or by [email](mailto:panieravide@riseup.net).
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
The website relies on the following technologies and components:
|
||||
|
||||
- Frontend website made in [Vue 3](https://vuejs.org/guide/introduction.html)
|
||||
- Project use [Vite](https://vitejs.dev/guide/) who offer a fast development server and an optimized compilation for production (like webpack)
|
||||
- The style is made with CSS/SASS and the [bootstrap library](https://getbootstrap.com/)
|
||||
- [Typescript](https://www.typescriptlang.org/) used to type
|
||||
- [Jest](https://jestjs.io/fr/) used for unit testing
|
||||
|
||||
|
||||
## All the docs
|
||||
|
||||
You might want to dive into docs :
|
||||
|
||||
- [Install and setup](./02_Setup.md)
|
||||
- [Change the settings](./03_Settings.md)
|
||||
- [Work on the code](./09_Develop.md)
|
||||
120
docs/02_Setup.md
120
docs/02_Setup.md
@@ -2,81 +2,63 @@
|
||||
|
||||
GeoVisio website can be installed through classic method, or using Docker.
|
||||
|
||||
__Contents__
|
||||
=== ":gear: Classic"
|
||||
|
||||
[[_TOC_]]
|
||||
You need to have installed on your system:
|
||||
|
||||
* [NodeJS](https://nodejs.org/en/download) >= 18.13.0
|
||||
* [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) or [Yarn](https://yarnpkg.com/)
|
||||
|
||||
The website can be installed locally by retrieving this repository and installing dependencies:
|
||||
|
||||
```bash
|
||||
# Retrieve source code
|
||||
git clone https://gitlab.com/panoramax/server/website.git
|
||||
cd website/
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
Then, you need to define some settings. You have to create a `.env` file and edit its content.
|
||||
|
||||
```sh
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
See _Configuration_ for more details about available settings.
|
||||
|
||||
Then, building for production can be done with these commands:
|
||||
|
||||
```sh
|
||||
npm run build
|
||||
PORT=3000 npm run start
|
||||
```
|
||||
|
||||
The website is now available at [localhost:3000](http://localhost:3000).
|
||||
|
||||
|
||||
## Classic install
|
||||
=== ":simple-docker: Docker"
|
||||
|
||||
### System requirements
|
||||
The [Docker](https://docs.docker.com/get-docker/) deployment is a really convenient way to have a Geovisio website running in an easy and fast way. Note that this setup documentation only covers __GeoVisio front-end__ (website), if you also need an API running, please refer to [Docker API deployment](https://gitlab.com/panoramax/server/api/-/blob/develop/docs/14_Running_Docker.md).
|
||||
|
||||
**You need to have [Nodejs installed](https://nodejs.org/en/download)**
|
||||
Node version : >=18.13.0
|
||||
You can use the provided __Docker Hub__ `geovisio/website:latest` image directly:
|
||||
|
||||
**You need to have [Npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)**
|
||||
```bash
|
||||
docker run \
|
||||
-e VITE_API_URL="https://your.geovisio.api/" \
|
||||
-e VITE_INSTANCE_NAME="My Own GeoVisio" \
|
||||
-e VITE_TILES="https://your.geovisio.api/vector/tiles/style.json" \
|
||||
-p 3000:3000 \
|
||||
--name geovisio-website \
|
||||
-d \
|
||||
geovisio/website:latest
|
||||
```
|
||||
|
||||
You can use npm or [yarn](https://yarnpkg.com/) as package manager
|
||||
This will run a container bound on [localhost:3000](http://localhost:3000).
|
||||
|
||||
### Install
|
||||
You can also build the image from the local source with:
|
||||
|
||||
The website can be installed locally by retrieving this repository and installing dependencies:
|
||||
|
||||
```sh
|
||||
# Retrieve source code
|
||||
git clone https://gitlab.com/panoramax/server/website.git
|
||||
cd website/
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
### Build for production
|
||||
|
||||
Before building, you need to define a bit of settings. At least, you have to create a `.env` file and edit its content.
|
||||
|
||||
```sh
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
More details about settings [can be found in docs here](./03_Settings.md).
|
||||
|
||||
Then, building for production can be done with these commands:
|
||||
|
||||
```sh
|
||||
npm run build
|
||||
PORT=3000 npm run start
|
||||
```
|
||||
|
||||
The website is now available at [localhost:3000](http://localhost:3000).
|
||||
|
||||
|
||||
## Docker setup
|
||||
|
||||
The [Docker](https://docs.docker.com/get-docker/) deployment is a really convenient way to have a Geovisio website running in an easy and fast way. Note that this setup documentation only covers __GeoVisio front-end__ (website), if you also need an API running, please refer to [Docker API deployment](https://gitlab.com/panoramax/server/api/-/blob/develop/docs/14_Running_Docker.md).
|
||||
|
||||
You can use the provided __Docker Hub__ `geovisio/website:latest` image directly:
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-e VITE_API_URL="https://your.geovisio.api/" \
|
||||
-e VITE_INSTANCE_NAME="My Own GeoVisio" \
|
||||
-e VITE_TILES="https://your.geovisio.api/vector/tiles/style.json" \
|
||||
-p 3000:3000 \
|
||||
--name geovisio-website \
|
||||
-d \
|
||||
geovisio/website:latest
|
||||
```
|
||||
|
||||
This will run a container bound on [localhost:3000](http://localhost:3000).
|
||||
|
||||
You can also build the image from the local source with:
|
||||
|
||||
```bash
|
||||
docker build -t geovisio/website:latest .
|
||||
```
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
You can check out [the available settings for your instance](./03_Settings.md).
|
||||
```bash
|
||||
docker build -t geovisio/website:latest .
|
||||
```
|
||||
|
||||
@@ -8,17 +8,17 @@ Low-level settings can be changed through the `.env` file. An example is given i
|
||||
|
||||
Available parameters are:
|
||||
|
||||
- `VITE_API_URL`: the URL to the GeoVisio API (with trailing `/`, example: `https://geovisio.fr/`)
|
||||
- `VITE_API_URL`: the URL to the GeoVisio API (example: `https://panoramax.ign.fr/`)
|
||||
- `VITE_INSTANCE_NAME`: the name of the instance (example: `IGN`)
|
||||
- `VITE_TILES`: the URL of your tiles : default tiles are the Open Street Map Tiles (example: `https://data.geopf.fr/annexes/ressources/vectorTiles/styles/PLAN.IGN/standard.json`)
|
||||
- `VITE_TILES`: the URL of your tiles : default tiles are the OpenStreetMap Tiles (example: `https://data.geopf.fr/annexes/ressources/vectorTiles/styles/PLAN.IGN/standard.json`)
|
||||
- `VITE_MAX_ZOOM`: the max zoom to use on the map (defaults to 24).
|
||||
- `VITE_ZOOM`: the zoom to use at the initialization of the map (defaults to 0).
|
||||
- `VITE_CENTER`: the center position to use at the initialization of the map (defaults to 0).
|
||||
- `VITE_RASTER_TILE`: the raster tile. Example : `https://maplibre.org/maplibre-style-spec/sources/#raster`.
|
||||
- Settings for the work environment:
|
||||
- `NPM_CONFIG_PRODUCTION`: is it production environment (`true`, `false`)
|
||||
- `YARN_PRODUCTION`: same as below, but if you use Yarn instead of NPM
|
||||
- `VITE_ENV`: `dev`
|
||||
- `NPM_CONFIG_PRODUCTION`: is it production environment (`true`, `false`)
|
||||
- `YARN_PRODUCTION`: same as below, but if you use Yarn instead of NPM
|
||||
- `VITE_ENV`: `dev`
|
||||
|
||||
More settings are available [in official Vite documentation](https://vitejs.dev/guide/env-and-mode.html#env-files)
|
||||
|
||||
@@ -28,21 +28,17 @@ Note that you can also change the _Vite_ server configuration in the `vite.confi
|
||||
|
||||
GeoVisio website can be customized to have wording reflecting your brand, licence and other elements.
|
||||
|
||||
All the wordings of the website are on this [locale file](./src/locales/fr.json). In there, you might want to change:
|
||||
All the wordings of the website are on this [locale file](https://gitlab.com/panoramax/server/website/-/blob/develop/src/locales/en.json). In there, you might want to change:
|
||||
|
||||
- The website title (properties `title` and `meta.title`)
|
||||
- The description (property `meta.description`)
|
||||
- Links to help pages:
|
||||
- `upload.description`
|
||||
- `upload.footer_description_terminal`
|
||||
- `upload.description`
|
||||
- `upload.footer_description_terminal`
|
||||
|
||||
## Visuals
|
||||
|
||||
The following images can be changed to make the website more personal:
|
||||
|
||||
- Logo: [`src/assets/images/logo.jpeg`](../src/assets/images/logo.jpeg)
|
||||
- Favicon: [`static/favicon.ico`](../static/favicon.ico)
|
||||
|
||||
## Next steps
|
||||
|
||||
You may be interested [in developing on the website](./09_Develop.md).
|
||||
- Logo: [`src/assets/images/logo.jpeg`](https://gitlab.com/panoramax/server/website/-/blob/develop/src/assets/images/logo.jpeg)
|
||||
- Favicon: [`static/favicon.ico`](https://gitlab.com/panoramax/server/website/-/blob/develop/static/favicon.ico)
|
||||
|
||||
@@ -1,10 +1,16 @@
|
||||
# Work on the code
|
||||
|
||||
## Available commands
|
||||
## Architecture
|
||||
|
||||
Note that all the commands and packages used are available in the `package.json` file.
|
||||
The website relies on the following technologies and components:
|
||||
|
||||
### Compile and Hot-Reload for Development
|
||||
- Frontend website made in [Vue 3](https://vuejs.org/guide/introduction.html)
|
||||
- Project use [Vite](https://vitejs.dev/guide/) who offer a fast development server and an optimized compilation for production (like webpack)
|
||||
- The style is made with CSS/SASS and the [bootstrap library](https://getbootstrap.com/)
|
||||
- [Typescript](https://www.typescriptlang.org/) used to type
|
||||
- [Jest](https://jestjs.io/fr/) used for unit testing
|
||||
|
||||
## Compile and Hot-Reload for Development
|
||||
|
||||
Launch your dev server :
|
||||
|
||||
@@ -18,7 +24,7 @@ or
|
||||
yarn dev
|
||||
```
|
||||
|
||||
### Run Unit Tests with [Vitest](https://vitest.dev/)
|
||||
## Run Unit Tests with [Vitest](https://vitest.dev/)
|
||||
|
||||
```sh
|
||||
npm run test:unit
|
||||
@@ -30,7 +36,7 @@ or
|
||||
yarn test:unit
|
||||
```
|
||||
|
||||
### Lint with [ESLint](https://eslint.org/)
|
||||
## Lint with [ESLint](https://eslint.org/)
|
||||
|
||||
```sh
|
||||
npm run lint
|
||||
@@ -41,3 +47,14 @@ or
|
||||
```sh
|
||||
yarn lint
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation is located `docs` folder, and can be served with [Mkdocs](https://www.mkdocs.org/):
|
||||
|
||||
```bash
|
||||
python -m venv env
|
||||
source ./env/bin/activate
|
||||
pip install mkdocs-material
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# Make a release
|
||||
|
||||
The web site uses [semantic versioning](https://semver.org/) for its release numbers.
|
||||
The website uses [semantic versioning](https://semver.org/) for its release numbers.
|
||||
|
||||
__Note__ : make sure that versions are in-sync with other Website components. Each component can have different `PATCH` versions, but compatibility __must__ be ensured between `MAJOR.MINOR` versions.
|
||||
!!! note
|
||||
Make sure that versions are in-sync with other GeoVisio components. Each component can have different `PATCH` versions, but compatibility __must__ be ensured between `MAJOR.MINOR` versions.
|
||||
|
||||
Run these commands in order to issue a new release:
|
||||
|
||||
|
||||
15
docs/index.md
Normal file
15
docs/index.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Panoramax instance Website
|
||||
|
||||
Welcome to GeoVisio __Website__ documentation ! It will help you through all phases of setup, run and develop on GeoVisio Website.
|
||||
|
||||
The website offers these functionalities:
|
||||
|
||||
- Display of pictures and their location (using the embed [web viewer](https://gitlab.com/panoramax/clients/web-viewer))
|
||||
- Handle user authentication and account management
|
||||
- Show simple to read documentation
|
||||
|
||||
!!! note
|
||||
The 📷 __web viewer__ (component showing pictures and their location on a map) is in [a separate, dedicated repository](https://gitlab.com/panoramax/clients/web-viewer). If you're looking for docs on another component, you may go to [this page](https://gitlab.com/panoramax) instead.
|
||||
|
||||
!!! note
|
||||
If at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/panoramax/server/website/-/issues) or by [email](mailto:panieravide@riseup.net).
|
||||
42
mkdocs.yml
Normal file
42
mkdocs.yml
Normal file
@@ -0,0 +1,42 @@
|
||||
site_name: 'Panoramax - Website'
|
||||
site_url: https://docs.panoramax.fr
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: https://gitlab.com/panoramax/gitlab-profile/-/raw/main/images/panoramax_favicon.svg
|
||||
features:
|
||||
- navigation.footer
|
||||
- navigation.tracking
|
||||
- navigation.sections
|
||||
- search.suggest
|
||||
- search.share
|
||||
- content.code.annotate
|
||||
- content.code.copy
|
||||
- content.code.select
|
||||
|
||||
plugins:
|
||||
- search
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- attr_list
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
|
||||
nav:
|
||||
- Home: 'index.md'
|
||||
- Install: '02_Setup.md'
|
||||
- Configuration: '03_Settings.md'
|
||||
- Developping:
|
||||
- 'Where to start': '09_Develop.md'
|
||||
- 'Make a release': '90_Releases.md'
|
||||
Reference in New Issue
Block a user