add: contribute and fix routes (#3)

6G-SANDBOX · Jan 28, 2025 · 24c9aa5 · 24c9aa5
1 parent 4fb8365
commit 24c9aa5
Show file tree

Hide file tree

Showing 10 changed files with 256 additions and 455 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,23 @@
-# 6G-SANDBOX TOOLS DOCS
+<a name="readme-top"></a>
 
-## Getting Started Locally
+<div align="center">
+
+# 6G-SANDBOX TOOLS DOCS <!-- omit in toc -->
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+<a href="https://github.com/6G-SANDBOX/docs"><img src="./static/img/logo.png" width="300" title="docs"></a>
+
+[![docs][docs-badge]][docs-url]
+
+[Report error](https://github.com/6G-SANDBOX/docs/issues/new?assignees=&labels=&projects=&template=bug_report.md) · [Feature request](https://github.com/6G-SANDBOX/docs/issues/new?assignees=&labels=&projects=&template=feature_request.md)
+
+</div>
+
+## :rocket: Getting Started Locally
 
 Clone repository
 
@@ -29,5 +46,26 @@ bun install
 Start server
 
 ```bash
-bun start
-```
+bun dev
+```
+
+## :rocket: Getting Started Web
+
+Docusaurus provides a [workspace](https://docusaurus.io/docs/playground) online without the need to install any tools.
+
+You can choose between CodeSandbox or StackBlitz. **CodeSandbox** is recommended.
+
+Select JavaScript in CodeSandbox and log in with GitHub.
+
+<p align="right"><a href="#readme-top">Back to top&#x1F53C;</a></p>
+
+[docs-badge]: https://img.shields.io/badge/docs-v0.0.0-blue
+[docs-url]: https://github.com/6G-SANDBOX/docs/releases/tag/v0.0.0
+[contributors-shield]: https://img.shields.io/github/contributors/6G-SANDBOX/docs.svg?style=for-the-badge
+[contributors-url]: https://github.com/6G-SANDBOX/docs/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/6G-SANDBOX/docs.svg?style=for-the-badge
+[forks-url]: https://github.com/6G-SANDBOX/docs/network/members
+[stars-shield]: https://img.shields.io/github/stars/6G-SANDBOX/docs.svg?style=for-the-badge
+[stars-url]: https://github.com/6G-SANDBOX/docs/stargazers
+[issues-shield]: https://img.shields.io/github/issues/6G-SANDBOX/docs.svg?style=for-the-badge
+[issues-url]: https://github.com/6G-SANDBOX/docs/issues
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 2
+title: "Contributing"
+sidebar_label: "Contributing"
+draft: false
+---
+
+## :hammer_and_wrench: How to contribute
+
+### Set up your environment
+
+- **Fork the repository**: fork the project to your GitHub account to have your own copy. To do this, click the "Fork" button at the top right of the repository page on GitHub. This will create a copy of the repository in your GitHub account.
+
+    ```bash
+    https://github.com/6G-SANDBOX/docs
+    ```
+
+- **Clone your fork**: after forking, clone the repository to your local machine. To do this, copy the URL of your fork by clicking the green "Code" button.
+
+    ```bash
+    git clone <URL of your fork>
+    ```
+
+- **Add the original repository as a remote**: to keep your fork updated with changes from the original repository, add the original repository as a remote.
+
+    ```bash
+    git remote add upstream <URL of the original repository>
+    ```
+
+### Add new section to the documentation
+
+To add a new section to the documentation, follow these steps:
+
+1. Create a branch from `main`. 
+
+    1.1. The branch name should follow the format `feature/<section_name>`.
+
+    1.2. The `<section_name>` should be meaningful.
+
+    ```bash
+    git switch -c feature/<section_name> main
+    ```
+
+2. Create a directory inside the [`docs`](./docs/) directory.
+
+    2.1. The name of the directory must be `<section_name>`.
+
+    2.2. If the directory name requires spaces, separate words using **-**.
+
+3. Add files to the new directory `<section_name>`.
+
+    3.1. Include a `_category_.json` file with the following structure:
+
+    ```json
+    {
+        "position": 2.5,
+        "label": "<section_name>",
+        "collapsible": true,
+        "collapsed": false,
+        "className": "red",
+        "link": {
+            "type": "generated-index",
+            "title": "<section_name> overview"
+        },
+        "customProps": {
+            "description": ""
+        }
+    }
+    ```
+
+    3.2. Add as many markdown files as required for the new documentation section. Each markdown file must begin with the following structure:
+
+    ```markdown
+    ---
+    sidebar_position: 1
+    title: "Home"
+    sidebar_label: "Home"
+    draft: false
+    ---
+    ```
+
+    3.3. The first heading level in the markdown file should be **##**. Please avoid using **#**.
+
+    3.4. If the markdown file name requires spaces, separate words using **-**.
+
+    3.5. If the documentation requires images, create a directory named `<section_name>` inside the [`img`](./static/img/) directory.
+
+4. You can test the rendering of your documentation locally or by using [tools](https://docusaurus.io/docs/playground) provided by Docusaurus. Refer to the [README](https://github.com/6G-SANDBOX/docs/blob/main/README.md) file for more information.
+
+5. Commit the changes to your branch.
+
+    ```bash
+    git add .
+    git commit -m "Add new <section_name> section to the documentation"
+    ```
+
+6. Push the changes to your fork.
+
+    ```bash
+    git push origin feature/<section_name>
+    ```
+
+7. Create a pull request on GitHub, go to your docs fork and click "Pull request" to start one. The pull request should be from your branch to the `main` branch of the original repository.
+
+    8.1. Include **@CarlosAndreo** or **alvarocurt** as a reviewer.
+
+    8.2. The pull request must include:
+
+    * The **new section directory** inside docs directory.
+    * The **images of the new section** inside img directory (if required).
+
+8. Once the pull request has been reviewed, the changes will be merged into the `main` branch of the original repository.
+
+### Update documentation section
+
+To update a documentation section, follow these steps:
+
+1. Create a branch from `main`. 
+
+    1.1. The branch name should follow the format `fix/<section_name>`.
+
+    1.2. The `<section_name>` must be a directory that must exist in the documentation.
+
+    ```bash
+    git switch -c fix/<section_name> main
+    ```
+
+2. Update the directory created inside the [`docs`](./docs/) directory.
+
+3. You can test the rendering of your documentation locally or by using [tools](https://docusaurus.io/docs/playground) provided by Docusaurus. Refer to the [README](https://github.com/6G-SANDBOX/docs/blob/main/README.md) file for more information.
+
+4. Commit the changes to your branch.
+
+    ```bash
+    git add .
+    git commit -m "Fix <section_name> section documentation"
+    ```
+
+5. Push the changes to your fork.
+
+    ```bash
+    git push origin fix/<section_name>
+    ```
+
+6. Create a pull request on GitHub, go to your docs fork and click "Pull request" to start one. The pull request should be from your branch to the `main` branch of the original repository.
+
+    8.1. Include **@CarlosAndreo** or **alvarocurt** as a reviewer.
+
+    8.2. The pull request must include:
+
+    * The **section directory** updated inside docs directory.
+    * The **images of the section** inside img directory (if required).
+
+7. Once the pull request has been reviewed, the changes will be merged into the `main` branch of the original repository.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -10,15 +10,15 @@ import {themes as prismThemes} from 'prism-react-renderer';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: '6G-SANDBOX TOOLS DOCS',
-  tagline: 'European project',
+  title: '6G-SANDBOX TOOLS',
+  tagline: 'A Horizon-JU Funded Research Project',
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
   url: 'https://6G-SANDBOX.github.io',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/docs/',
+  baseUrl: '/docs',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
@@ -44,7 +44,8 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
-          sidebarPath: './sidebars.js'
+          sidebarPath: './sidebars.js',
+          routeBasePath: '/', // Serve the docs at the site's root
         },
         // blog: {
         //   showReadingTime: true,
@@ -72,15 +73,15 @@ const config = {
       navbar: {
         title: '6G-SANDBOX',
         logo: {
-          alt: '6G-SANDBOX Logo',
+          alt: 'logo',
           src: 'img/logo.png',
         },
         items: [
           {
             type: 'docSidebar',
             sidebarId: 'documentationSidebar',
             position: 'left',
-            label: 'DOCUMENTATION',
+            label: 'DOCS',
           },
           // {to: '/blog', label: 'BLOG', position: 'left'},
           {
@@ -89,6 +90,7 @@ const config = {
             position: 'right',
           },
         ],
+        hideOnScroll: true,
       },
       footer: {
         style: 'dark',
@@ -98,7 +100,7 @@ const config = {
             items: [
               {
                 label: 'Documentation',
-                to: '/docs/intro',
+                to: '/docs/introduction',
               },
             ],
           },
@@ -139,6 +141,13 @@ const config = {
         theme: prismThemes.github,
         darkTheme: prismThemes.dracula,
       },
+      docs: {
+        versionPersistence: 'localStorage',
+        sidebar: {
+          hideable: true,
+          autoCollapseCategories: true,
+        },
+      }
     }),
 };
 

diff --git a/sidebars.js b/sidebars.js
@@ -19,17 +19,9 @@ const sidebars = {
   documentationSidebar: [{type: 'autogenerated', dirName: '.'}],
 
   // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-   */
+  // documentationSidebar: [
+  //   'introduction',
+  // ],
 };
 
 export default sidebars;