feat(doc): Add user/dev/admin documentation

.github/DISCUSSION_TEMPLATE/user-personas-and-stories.yaml

@@ -4,7 +4,7 @@ body:
     attributes:
       value: >
         Develop a user persona and a story to capture the goals and tasks your users want to accomplish with diracx-web.
-        We are interested in understanding your needs and goals. Please focus on what you want to achieve rather than how you think it should be achieved.
+        We are interested in understanding your needs and goals. Please, first focus on what you want to achieve rather than how you think it should be achieved first.
         All ideas are welcome, and there are no wrong answers. We appreciate your honest feedback as it helps us improve the system to better meet your needs.
 
   - type: textarea
@@ -43,10 +43,27 @@ body:
     validations:
       required: true
 
+  - type: markdown
+    attributes:
+      value: |
+        From this point, you can optionally propose ideas of how it should be conceived, even if you technically do not know whether it is achievable.
+
   - type: textarea
-    id: additional-comments
+    id: design-solution
     attributes:
-      label: Additional Comments or Suggestions
-      description: "Share any other feedback, ideas, or suggestions that can help us understand your needs better."
-    validations:
-      required: false
+      label: Proposed Design Solution
+      description: |
+        Design proposal(s) can be submitted here.
+        Explain how your design solves the problem. Describe the design changes in details.
+      placeholder: "Describe your design solution..."
+
+  - type: markdown
+    attributes:
+      value: |
+        If possible, please attach an image representing a mockup or sketch of your design idea. Visual representations can help communicate your idea more clearly.
+
+  - type: markdown
+    attributes:
+      value: |
+        Once again, thank you for your contribution. Our team will review your design proposal(s) and provide feedback.
+

CONTRIBUTING.md

@@ -1,67 +1,17 @@
-# Contributing to This Project
+# Contributing to DiracX-Web
 
 Thank you for your interest in contributing to our project! We appreciate all contributions, big and small. Below are some guidelines to help you get started.
 
-## Bug reporting and discussions
+- **Found a :bug: bug?**
+  - First if someone has already reported a similar [Issue](https://github.com/DIRACGrid/diracx-web/issues).
+  - If not, feel free to open a new one.
 
-- Want to report a bug?
-  Open an [Issue](https://github.com/DIRACGrid/diracx-web/issues).
-- Need technical support to configure `diracx-web`?
-  Start a [Support discussion](https://github.com/DIRACGrid/diracx-web/discussions/categories/support).
+- **Need :hammer_and_wrench: technical support to configure DiracX-Web?**
+  - Start by reading the [:book: Admin Guide](docs/admin/index.md).
+  - Still stuck? Start a [:pray: Support discussion](https://github.com/DIRACGrid/diracx-web/discussions/categories/support).
 
-- Want to make a general feedback about the [DIRAC web application](https://github.com/DIRACGrid/WebAppDIRAC)?
-  Answer to the [Survey](https://github.com/DIRACGrid/diracx-web/discussions/categories/surveys) by creating a new discussion.
-- Want to request a feature?
-  Create a [User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need.
-- Want to discuss about UX/UI design?
-  Share your [Design idea](https://github.com/DIRACGrid/diracx-web/discussions/categories/design-ideas).
+- **Have a :bulb: feature proposal?**
+  - Create a [:bust_in_silhouette: User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need and share your design ideas if any.
 
-## How to Contribute
-
-### 1. Opening an Issue
-
-- **Discuss Before Implementing:** Before making a pull request (PR), especially for non-trivial changes, please [open an issue](https://github.com/DIRACGrid/diracx-web/issues) to discuss your idea. This ensures that everyone is aligned on the proposed change.
-- **Check for Existing Issues:** Before opening a new issue, please check if a similar issue already exists. If a similar issue exists, consider contributing to the discussion there instead.
-
-### 2. Making Changes
-
-- **Code Documentation:** Ensure that any code you write is well-documented. This includes:
-  - Inline comments where necessary to explain complex logic.
-  - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library.
-- **Writing/Updating Tests:** When you change or add new code, make sure to write or update tests accordingly. This helps maintain the reliability and stability of the codebase.
-- **Helping with Existing Issues:** If you want to start contributing right away, check out the issues labeled with ["good first issue"](https://github.com/DIRACGrid/diracx-web/labels/good%20first%20issue). These are issues that are well-suited for newcomers to the project.
-
-### 3. Commit Messages
-
-- **Conventional Commits:** All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This ensures that commit messages are structured and consistent, which is important for automation and versioning.
-  - **Examples:**
-    - `feat(ui): add new button component`
-    - `fix(api): handle null values in response`
-    - `docs(readme): update contributing guidelines`
-  - **Why?** If your commit messages do not follow this convention, the Continuous Integration (CI) process will fail, and your PR will not be merged. Please ensure your commit messages are properly formatted before pushing.
-
-### 4. How to Make a Pull Request (PR)
-
-- **Fork the Repository:** Start by forking the repository and creating a new branch for your work. Use a descriptive name for your branch that reflects the work you're doing.
-- **Make Your Changes:** Commit your changes with clear and concise commit messages following the Conventional Commits format.
-- **Update Documentation and Tests:** As mentioned, ensure all relevant documentation and tests are updated to reflect your changes.
-- **Submit Your PR:** When you’re ready, submit your pull request. Please include a clear description of what your PR does and reference the issue number it addresses (if applicable).
-- **Review Process:** Your PR will be reviewed by project maintainers. Please be patient and responsive to any feedback you receive.
-
-### 5. Updating Storybook Stories
-
-If your changes affect the `diracx-web-components` library, you may need to update or add new Storybook stories to ensure components are well-documented and tested visually.
-
-- **Add New Stories:** If you’ve created a new component, add a corresponding Storybook story in the appropriate directory. This story should be placed inside a `*.stories.tsx` file alongside your new component.
-- **Update Existing Stories:** If your changes modify the behavior or appearance of an existing component, make sure to update its Storybook story accordingly.
-- **Run Storybook Locally:** Before submitting your PR, run Storybook locally to ensure that your changes are reflected correctly. You can do this by running `npm run storybook` in the `packages/diracx-web-components` directory.
-
-You can check the existing stories and the [Storybook documentation](https://storybook.js.org/docs) for more details on how to use Storybook.
-
-### 6. Additional Notes
-
-- **Trivial Changes:** For minor changes like fixing typos, feel free to skip the issue creation step and go straight to making a PR.
-- **Stay Up-to-Date:** Make sure your branch is up-to-date with the latest changes in the main branch before submitting your PR. Use `git rebase` if necessary.
-- **Project Setup:** See the README for instructions on how to set up the project and run tests locally.
-
-Thank you again for your contributions! We look forward to working with you.
+- **Want to contribute to the :computer: codebase?**
+  - Read the [:book: Developer Guide](docs/developer/index.md) to set up your environment and get started.

README.md

@@ -1,116 +1,24 @@
+<p align="center">
+  <img alt="Extension Logo" src="packages/diracx-web/public/DIRAC-logo-minimal.png" width="200" >
+</p>
+
+# DiracX-Web
 ![Basic tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/basic.yml/badge.svg?branch=main)
 ![Unit tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/test.yml/badge.svg?branch=main)
 ![Integration tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/integration-test.yml/badge.svg?branch=main)
 ![Deployment](https://github.com/DIRACGrid/diracx-web/actions/workflows/deployment.yml/badge.svg?branch=main)
 
-# DiracX-Web
-
-## Overview
-
-`diracx-web` is a web application that provides a user interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) service and is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem.
-
-This repository is organized as a monorepo, with the following key packages:
-
-- [diracx-web](packages/diracx-web)
-- [diracx-web-components](packages/diracx-web-components)
-- [extensions](packages/extensions)
-
-```mermaid
----
-config:
-  layout: elk
----
-flowchart TD
- subgraph monorep["Monorepo"]
-        monorep1["diracx-web-components"]
-        monorep2["diracx-web"]
-        monorep3["extension[gubbins]"]
-  end
-    monorep2 -- images deployed in --> docker[" "]
-    monorep2 -. uses .-> monorep1
-    monorep3 -. uses .-> monorep1
-    monorep1 -- documented on --> storybook[" "]
-    monorep1 -- published on --> npm[" "]
-    extension["diracx-community-extension"] -. uses .-> npm
-    docker@{ img: "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQLQKd_MRed_mZQlgrzQuUXVA3P39ssOVX8_g&s", h: 100, w: 100}
-    storybook@{ img: "https://miro.medium.com/v2/resize:fit:900/1*ZuBTYHXl6l3XzTb8d9Oi5Q.png", h: 100, w: 150, pos: "b"}
-    npm@{ img: "https://upload.wikimedia.org/wikipedia/commons/thumb/d/db/Npm-logo.svg/2560px-Npm-logo.svg.png", h: 40, w: 100}
-     monorep1:::Ash
-     monorep1:::Cyan
-     monorep2:::Green
-     monorep3:::Green
-     extension:::Ash
-    classDef Cyan stroke-width:1px, stroke-dasharray:none, stroke:#00FFFF, fill:#9CFFFF
-    classDef Green stroke-width:1px, stroke-dasharray:none, stroke:#5BFF00, fill:#A4FF8E, color:#374D7C
-    classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000
-```
-
-### Packages
-
-- **DiracX-Web**: Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities.
-
-- **DiracX-Web-Components**: A library of reusable React components designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions.
-
-- **Extensions**: An illustrative example of a web extension demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package.
-
-### Project Management
-
-- [**npm**](https://docs.npmjs.com/): Used for dependency management.
-- [**Release-Please**](https://github.com/googleapis/release-please): Automated release management for the project.
-
-The dependency management is further detailed in the [Package Management](docs/package-management.md) documentation.
-
-For more detailed and interactive documentation, visit our [Storybook](https://diracgrid.github.io/diracx-web) instance.
-
-## Getting started
-
-_Requirements: docker, internet_
-
-This will allow you to run a demo setup:
-
-```bash
-# Clone the diracx-chart repository
-git clone git@github.com:DIRACGrid/diracx-charts.git
-
-# Run the demo
-diracx-charts/run_demo.sh
-```
-
-You can also start the demo setup in development mode - code changes will be reflected in the demo in real time:
-
-```bash
-# Clone the diracx-web repository
-git clone git@github.com:DIRACGrid/diracx-web.git
-
-# Clone the diracx-chart repository
-git clone git@github.com:DIRACGrid/diracx-charts.git
-
-# Run the demo
-diracx-charts/run_demo.sh ./diracx-web
-```
-
-## Contributing
-
-See the [Contributing guidelines](/CONTRIBUTING.md)
 
-## Testing
+**DiracX-Web** is a web application that provides a user-friendly interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) services. It is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem.
 
-Unit tests can be started with:
+## Get Started
 
-```bash
-npm test
-```
 
-End-to-end tests are launched through `cypress` such as:
+- **New user?** Learn how to use the application effectively in the [:book: User Guide](docs/user/index.md)
+- **Developing a DiracX-Web extension?** Go straight to the [:page_facing_up: Extension README](packages/extensions/README.md)
+- **Deploying your own instance?** Discover tips and tricks in the [:book: Admin Guide](docs/admin/index.md)
 
-```bash
-# diracx-charts/run_demo.sh is running
-npx cypress open --config baseUrl=$DIRACX_URL
-```
+- **Interested in contributing?** Read the [:star: Contributing Document](CONTRIBUTING.md)
 
-## Learn More
 
-To learn more about Next.js, take a look at the following resources:
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

docs/admin/deploy_instance.md

@@ -0,0 +1,3 @@
+# Deployment
+
+Link to diracx-charts values

docs/admin/manage_dependencies.md

@@ -0,0 +1,3 @@
+# Dependencies Management
+
+- [**npm**](https://docs.npmjs.com/): Used for dependency management.

docs/admin/manage_release.md

@@ -0,0 +1,6 @@
+# Release Management
+
+
+- [**Release-Please**](https://github.com/googleapis/release-please): Automated release management for the project.
+
+For more detailed and interactive documentation, visit our [Storybook](https://diracgrid.github.io/diracx-web) instance.