Move information in the README to the Vitepress documentation

SkwalExe · Jun 10, 2024 · 73f3ab8 · 73f3ab8
1 parent c8c719b
commit 73f3ab8
Show file tree

Hide file tree

Showing 10 changed files with 155 additions and 168 deletions.
diff --git a/README.md b/README.md
@@ -11,20 +11,18 @@
 
 </p>
 
-<p align="center">💠 Simple program that generates a logo for your open source projects 💠</p>
+<p align="center">💠 Simple logos for complex projects. 💠</p>
 
-# Credits
+# Documentation
 
-I had the idea to create this project after seeing the logos made by [adi1090x](https://github.com/adi1090x) for his repositories. They were simple but gave a nice feel to his projects. I wanted a logo that gives the same energy, but didn't manage to find how he made them (most likely manually, with GIMP according the the exif data of the images). So I decided to make a program that would allow anyone to generate a cool and simple logo for their projects.
-
-- [adi1090x's GitHub](https://github.com/adi1090x)
+[**--> Please head over to our documentation for more information! <--**](https://octologo.skwal.net)
 
 # How to install 📥
 
 You can install octologo easily with pip:
 
 ```bash
-python3 -m pip install octologo
+pip install octologo
 ```
 
 You can also use [pipx](https://pypa.github.io/pipx/):
@@ -33,164 +31,8 @@ You can also use [pipx](https://pypa.github.io/pipx/):
 pipx install octologo
 ```
 
-Now, start the app with:
-
-```bash
-octologo
-```
-
-> [!CAUTION]
-> If the command is not found after installtion, you must add  `~/.local/bin` to your path. You can do this by adding `export PATH=$PATH:~/.local/bin` to your `.bashrc` or `.zshrc` file.
-
-```bash
-# For bash
-echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
-
-# For zsh
-echo 'export PATH=$PATH:~/.local/bin' >> ~/.zshrc
-```
-
-# Styles
-
-### Style 1 - First letters underlined
-
-> The number of letters to underline is customizable since version 2.0.0
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/SkwalExe/octo-logo/main/assets/style1.png">
-</p>
-
-
-# Color schemes
-
-### Color scheme 1 - adi1090x's color scheme
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/SkwalExe/octo-logo/main/assets/color1.png">
-</p>
-
-### Color scheme 2 - Cherry
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/SkwalExe/octo-logo/main/assets/color2.png">
-</p>
-
-### Color scheme 3 - Midnight Abyss
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/SkwalExe/octo-logo/main/assets/color3.png">
-</p>
+Now, start the app with the `octologo` command.
 
 # Contributing 🤝
 
-Please, open an issue if you have any suggestion or if you found a bug. I will try to fix it as soon as possible.
-
-## General Info About the Project 📖
-
-This is a terminal application that allows developers to generate logos for their projects. It uses the following technologies for the development process and for the build pipeline:
-
-- [PDM](https://pdm-project.org/en/latest/) for development scripts and managing (dev)dependencies.
-- [Ruff](https://docs.astral.sh/ruff/) for linting and formatting
-- [Pyright](https://microsoft.github.io/pyright/#/) for type checking
-- [Pytest](https://docs.pytest.org/) for unit tests
-
-You can install PDM with the following command:
-
-```bash
-curl -sSL https://pdm-project.org/install-pdm.py | python3 -
-```
-
-## Setting up the development environment 🖥️
-
-- [Fork this repository to your own GitHub account.](https://github.com/SkwalExe/octo-logo/fork)
-
-- Clone your fork locally.
-
-```bash
-git clone https://github.com/YOUR_USERNAME/octo-logo
-cd ./octo-logo
-```
-
-- Install dependencies
-
-```bash
-pdm install
-```
-
-- You must configure your IDE to use the project's venv or your extensions will fail to resolve the dependencies.
-
-- If you use a command line editor (like vim), you can activate the venv in your shell session then start vim.
-
-> [!CAUTION] 
-> This command must be run everytime you open a new shell session.
-
-```bash
-# Activating the project's venv (linux)
-eval $(pdm venv activate)
-vim
-```
-
-## Files and directories 📂
-
-__Configuration Files:__ ⚙
-
-- `ruff.toml`: Ruff configuration file (for linting and formatting)
-- `pyproject.toml`: Python module configuration
-
-__Source:__ 🔢
-- `src/octologo/colors/`: Contains color schemes (.toml files).
-- `src/octologo/fonts/`: Contains font files that can be used in the app.
-- `src/octologo/styles/`: Contains available logo styles.
-- `src/octologo/__main__.py`: Application entry point.
-
-__Other:__ 📄
-
-- `assets/`: Assets for the GitHub repo only.
-- `tests/`: Unit test files (pytest).
-
-## Creating a pull request 👍
-
-If you'd like to contribute, please open an empty pull request and provide an explanation of your proposed changes. Once I approve it, you can begin your work. It's always disheartening to reject a pull request after someone has invested a lot of time and effort into it. 😿
-
-- Create a branch for your contribution
-
-```bash
-git checkout -b my-new-feature
-```
-
-- When you finished your changes, you must check your code's formatting and linting and fix all the errors.
-
-```bash
-pdm run format # Check for formatting errors (most errors should be automatically fixed)
-pdm run lint # Check for linting errors
-pdm run check-types # Check for type errors
-```
-
-- You also have to run tests to check if your changes didn't break anything
-
-```bash
-pdm run tests
-```
-
-- After that, add your changes to `CHANGELOG.md` and update the README if needed.
-
-- Do not increment the module version yourself, the maintainer will do it.
-
-- Then, you can commit your work and push to your fork.
-
-```bash
-git add --all 
-git commit -m "Added a new feature"
-git push -u origin my-new-feature
-```
-
-- Finally, you can create your pull request from your fork repo's github page.
-
-## PDM scripts
-
-- `format`: Checks for formatting errors and fixes them if possible.
-- `format-check`: Checks for formatting errors and exists with error code if any is found.
-- `lint`: Checks for linting errors and fixes them if possible.
-- `lint-check`: Check for linting errors and exits with error code if any is found.
-- `check-types`: Check for type errors with Pyright.
-- `tests`: Run all unit tests.
+**For contribution instructions, take a look at the `contributing` section of [our documentation](https://octologo.skwal.net/understanding-the-project.html).**
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -28,7 +28,14 @@ export default defineConfig({
                 text: "Introduction",
                 items: [
                     { text: "📥 Getting Started", link: "/getting-started" },
-                    { text: "🎨 Available Styles/Temes", link: "/available-styles" },
+                    { text: "🎨 Available Styles/Themes", link: "/available-styles/index.html" },
+                ],
+            },
+            {
+                text: "Contributing",
+                items: [
+                    { text: "🏗️ Understanding the Project", link: "/understanding-the-project" },
+                    { text: "🫂 Creating a Pull Request", link: "/pull-request" },
                 ],
             },
         ],

diff --git a/docs/src/available-styles.md b/docs/src/available-styles.md
diff --git a/assets/color1.png → docs/src/available-styles/color1.png b/assets/color1.png → docs/src/available-styles/color1.png
diff --git a/assets/color2.png → docs/src/available-styles/color2.png b/assets/color2.png → docs/src/available-styles/color2.png
diff --git a/assets/color3.png → docs/src/available-styles/color3.png b/assets/color3.png → docs/src/available-styles/color3.png
diff --git a/docs/src/available-styles/index.md b/docs/src/available-styles/index.md
@@ -0,0 +1,23 @@
+# Available Styles and Color Schemes
+
+The project's structure enables anyone to easily create new styles and color schemes, allowing the application to quickly gain diversity.
+
+## Available styles
+
+#### Style 1 - First letters underlined
+
+![Style 1](style1.png)
+
+## Available color schemes
+
+#### Color scheme 1 - adi1090x's color scheme
+
+![Color scheme 1](color1.png)
+
+#### Color scheme 2 - Cherry
+
+![Color scheme 2](color2.png)
+
+#### Color scheme 3 - Midnight Abyss
+
+![Color scheme 3](color3.png)
diff --git a/assets/style1.png → docs/src/available-styles/style1.png b/assets/style1.png → docs/src/available-styles/style1.png
diff --git a/docs/src/pull-request.md b/docs/src/pull-request.md
@@ -0,0 +1,72 @@
+# Creating a pull request
+
+If you'd like to contribute, please open an empty pull request and provide an explanation of your proposed changes. Once I approve it, you can begin your work. It's always disheartening to reject a pull request after someone has invested a lot of time and effort into it :(
+
+## Setting up the development environment 🖥️
+
+> Before starting, make sure you have `pdm` installed on your system. You can find the instructions in the [previous page](understanding-the-project#general-info).
+
+1. [Fork this repository to your own GitHub account.](https://github.com/SkwalExe/octo-logo/fork)
+
+2. Clone your fork locally.
+
+```bash
+git clone https://github.com/YOUR_USERNAME/octo-logo
+cd ./octo-logo
+```
+
+3. Install dependencies
+
+```bash
+pdm install
+```
+
+4. You must configure your IDE to use the project's venv (`./.venv`) or your extensions will fail to resolve the dependencies.
+
+5. If you use a command line editor (like vim), you can activate the venv in your shell session, then start vim.
+
+```bash
+# Activating the project's venv (linux)
+# This command must be run everytime you open a new shell session.
+eval $(pdm venv activate)
+vim
+```
+
+## Making the pull request 👍 {#making-the-pull-request}
+
+- Create a branch for your contribution
+
+```bash
+git checkout -b my-new-feature
+```
+
+- When you finished your changes, you must check your code's formatting and linting and fix all the errors.
+
+```bash
+pdm run format # Check for formatting errors (most errors should be automatically fixed)
+pdm run lint # Check for linting errors
+pdm run check-types # Check for type errors
+```
+
+- You also have to run tests to check if your changes didn't break anything
+
+```bash
+pdm run tests
+```
+
+- After that, add your changes to `CHANGELOG.md` and update the README if needed.
+
+- It would also be appreciated if you updated the documentation (`/docs`) according to your changes.
+
+- Do not increment the module version yourself, the maintainer will do it.
+
+- Now, you can commit your work and push to your fork.
+
+```bash
+git add --all 
+git commit -m "Added a new feature"
+git push -u origin my-new-feature
+```
+
+- Finally, you can create your pull request from your fork repo's github page.
+
diff --git a/docs/src/understanding-the-project.md b/docs/src/understanding-the-project.md
@@ -0,0 +1,46 @@
+# Understanding the Project's Structure
+
+## General Info About the Project 📖 {#general-info}
+
+This is a terminal application that allows developers to generate logos (maybe a better term would be banner) for their projects. It uses the following technologies for the development process and for the build pipeline:
+
+- [PDM](https://pdm-project.org/en/latest/) for development scripts and managing (dev)dependencies.
+- [Ruff](https://docs.astral.sh/ruff/) for linting and formatting
+- [Pyright](https://microsoft.github.io/pyright/#/) for type checking
+- [Pytest](https://docs.pytest.org/) for unit tests
+
+You can install PDM with the following command:
+
+```bash
+curl -sSL https://pdm-project.org/install-pdm.py | python3 -
+```
+
+The project also uses [`Vitepress`](https://vitepress.dev/) for generating the [documentation website](https://octologo.skwal.net).
+
+## Files and directories 📂 {#files-and-directories}
+
+__Configuration Files:__ ⚙
+
+- `ruff.toml`: Ruff configuration file (for linting and formatting)
+- `pyproject.toml`: Python module configuration
+
+__Source:__ 🔢
+- `src/octologo/colors/`: Contains color schemes (.toml files).
+- `src/octologo/fonts/`: Contains font files that can be used in the app.
+- `src/octologo/styles/`: Contains available logo styles.
+- `src/octologo/__main__.py`: Application entry point.
+
+__Other:__ 📄
+
+- `assets/`: Assets for the GitHub repo only.
+- `tests/`: Unit test files (pytest).
+- `docs/`: Documentation site (Vitepress)
+
+## PDM scripts
+
+- `format`: Checks for formatting errors and fixes them if possible.
+- `format-check`: Checks for formatting errors and exists with error code if any is found.
+- `lint`: Checks for linting errors and fixes them if possible.
+- `lint-check`: Check for linting errors and exits with error code if any is found.
+- `check-types`: Check for type errors with Pyright.
+- `tests`: Run all unit tests.