From 014d4b3870fc4be9e5d4e8447bdffe4c49570094 Mon Sep 17 00:00:00 2001 From: bruhnild Date: Thu, 17 Oct 2024 12:26:33 +0200 Subject: [PATCH] Improve documentation and dev setup pages --- docs/development/contributing.md | 27 ++++++++++-- docs/development/development.md | 41 ----------------- docs/development/installation.md | 75 ++++++++++++++++++++++++++++++++ docs/index.md | 6 +-- mkdocs/mkdocs.yml | 4 +- 5 files changed, 103 insertions(+), 50 deletions(-) delete mode 100644 docs/development/development.md create mode 100644 docs/development/installation.md diff --git a/docs/development/contributing.md b/docs/development/contributing.md index 2a8a3227e..b77690980 100644 --- a/docs/development/contributing.md +++ b/docs/development/contributing.md @@ -1,8 +1,10 @@ # Contributing -## Documentation +## Contributing to the documentation -To work on the documentation, you will need **Python 3** (this documentation was built using `Python 3.10.12`). +This section explains how to contribute to **the documentation** of the project. If you are interested in making changes to the codebase or contributing to other aspects of the project, please refer to the relevant sections of the contribution guide. + +To contribute to the documentation, you will need **Python 3**. The current version of the documentation has been built using `Python 3.10.12`. ### Running the documentation locally @@ -17,9 +19,26 @@ To preview the documentation locally in your environment, follow these steps: ```bash python3 -m mkdocs serve ``` -4. Your local documentation will be available with port 8000 at: +4. The local instance of the documentation will be accessible on port 8000 at: [http://127.0.0.1:8000/latest/](http://127.0.0.1:8000/latest/) ### Editing the documentation -You can also edit the documentation files directly on [GitHub](https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/docs). +You can directly modify the documentation files in the repository. They are located in the `/docs` folder. To make changes, you can clone the repository to your local machine and work on the files, or you can edit them directly online via GitHub. + +You can access the documentation files for editing on [GitHub](https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/docs). + +Make sure to follow the existing style and structure of the documentation to maintain consistency across the project. + +## Reporting bugs or requesting features + +If you encounter any bugs or have suggestions for new features, you can create a ticket in the GitHub issues section. Here's how to proceed: + +1. Visit the [issue creation page](https://github.com/GeotrekCE/Geotrek-rando-v3/issues/new). +2. Select the appropriate template for your issue (bug report, feature request, etc.). +3. Provide a clear and detailed description of the issue or the new feature you'd like to see implemented : + + - For bugs: Include steps to reproduce the problem, the expected behavior, and any relevant error messages or logs. + - For feature requests: Clearly describe the functionality you are proposing and why it would benefit the project. + +The development team will review the ticket and follow up with any questions or updates. diff --git a/docs/development/development.md b/docs/development/development.md deleted file mode 100644 index 540fc001d..000000000 --- a/docs/development/development.md +++ /dev/null @@ -1,41 +0,0 @@ -# Development - -Installation in development: - -## Prerequisite - -- You need to use a node version equal or above 20 -- Use nvm and then: - -```bash -nvm use -``` - -Install yarn - -```bash -npm install -g yarn -``` - -## Install dependencies - -Head to the `frontend` folder and run: - -```bash -yarn -``` - -## Start the app - -Once your dependencies are installed, start your server in development mode by running: - -```bash -yarn dev -``` - -## Customization - -To get the proper settings of the Geotrek-rando site in your local environnement : - -- Copy/cut the `customization` folder from a Geotrek-rando repository in Geotrek-rando-v3/frontend/customization -- Copy/cut the `medias` folder from a rando Geotrek-repository in Geotrek-rando-v3/frontend/src/public/medias diff --git a/docs/development/installation.md b/docs/development/installation.md new file mode 100644 index 000000000..4dad20a23 --- /dev/null +++ b/docs/development/installation.md @@ -0,0 +1,75 @@ +# Installation + +This section explains how to set up the project for development purposes. + +## Prerequisites + +Before starting the installation, ensure the following: + +- **Node.js**: You need to have **Node.js** version **20** or higher installed. +- **NVM (Node Version Manager)**: It's recommended to use `nvm` to manage your Node.js versions. + +To ensure you're using the correct Node version, run: + +```bash +nvm use +``` + +If you don't have `nvm` installed, you can find the installation instructions [here](https://github.com/nvm-sh/nvm). + +### Install Yarn + +To manage project dependencies, install Yarn globally if you haven't already: + +```bash +npm install -g yarn +``` + +You can verify the installation by running: + +```bash +yarn --version +``` + +## Installing dependencies + +Navigate to the `frontend` folder in your project directory: + +```bash +cd frontend +``` + +Then, install all the required dependencies by running: + +```bash +yarn +``` + +This will install all packages listed in the `package.json` file necessary for the frontend development. + +## Starting the application + +Once the dependencies are installed, you can start the development server by running: + +```bash +yarn dev +``` + +This command will start the application in development mode, typically accessible at [http://localhost:3000](http://localhost:3000). + +## Customization + +To apply the custom settings and media files for your local development environment, follow these steps: + +1. **Customization Settings**: + - Copy the `customization` folder from an existing Geotrek-rando repository. + - Paste it into the following directory in your project: + `Geotrek-rando-v3/frontend/customization` + +2. **Media Files**: + - Copy the `medias` folder from an existing Geotrek-rando repository. + - Paste it into this directory in your project: + `Geotrek-rando-v3/frontend/src/public/medias` + +These folders contain custom configurations and media assets necessary for your local environment to match the production setup. + diff --git a/docs/index.md b/docs/index.md index 2d58d3d64..e117cf0ef 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ Read more in the [general presentation](./presentation-fr.md). ## 🚀 Installation -- [Production installation](./installation.md) +- [Production setup](./installation.md) ## 🎨 Customization @@ -30,7 +30,7 @@ Read more in the [general presentation](./presentation-fr.md). ## 🔧 Development -- [Development installation](./development/development.md) +- [Installation](./development/installation.md) - [Deployment](./development/deployment.md) - [Contributing](./development/contributing.md) @@ -48,6 +48,6 @@ Read more in the [general presentation](./presentation-fr.md). ## 🪄 Getting started -- Follow the [development](./development/development.md) docs +- Follow the [development](./development/installation.md) docs - Head to [localhost:3000](http://localhost:3000) diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index c63a156a5..8a906a80a 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -137,7 +137,7 @@ nav: - 💡 Présentation: - Présentation générale: presentation-fr.md - 🚀 Installation: - - Production installation: installation.md + - Production setup: installation.md - 🎨 Customization: - Introduction: customization/customization-introduction.md - Settings: customization/customization-settings.md @@ -148,7 +148,7 @@ nav: - GDPR: customization/customization-gdpr.md - Media management: customization/customization-mediamanagement.md - 🔧 Development: - - Development installation: development/development.md + - Installation: development/installation.md - Deployment: development/deployment.md - Contributing: development/contributing.md - ✨ Knowledge: