diff --git a/.gitignore b/.gitignore index 478112d..b6cc598 100644 --- a/.gitignore +++ b/.gitignore @@ -93,4 +93,8 @@ sw.* cypress/downloads/* cypress/screenshot/ cypress/videos/ -*.cy.ts.mp4 \ No newline at end of file +*.cy.ts.mp4 + +# Mkdocs +env/ +site/ diff --git a/docs/01_Start.md b/docs/01_Start.md deleted file mode 100644 index 40f3cc2..0000000 --- a/docs/01_Start.md +++ /dev/null @@ -1,29 +0,0 @@ -# GeoVisio Website hands-on guide - -![GeoVisio logo](https://gitlab.com/panoramax/server/api/-/raw/develop/images/logo_full.png) - -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) diff --git a/docs/02_Setup.md b/docs/02_Setup.md index 7105c9e..3958ecf 100644 --- a/docs/02_Setup.md +++ b/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 . + ``` diff --git a/docs/03_Settings.md b/docs/03_Settings.md index efb104d..d483414 100644 --- a/docs/03_Settings.md +++ b/docs/03_Settings.md @@ -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) diff --git a/docs/09_Develop.md b/docs/09_Develop.md index f5cb092..637009e 100644 --- a/docs/09_Develop.md +++ b/docs/09_Develop.md @@ -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 +``` diff --git a/docs/90_Releases.md b/docs/90_Releases.md index 96e3a89..1cd886c 100644 --- a/docs/90_Releases.md +++ b/docs/90_Releases.md @@ -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: diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c1bf2de --- /dev/null +++ b/docs/index.md @@ -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). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..3320e6e --- /dev/null +++ b/mkdocs.yml @@ -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'