diff --git a/README.md b/README.md index 415343e..f006933 100644 --- a/README.md +++ b/README.md @@ -11,20 +11,18 @@

-

💠 Simple program that generates a logo for your open source projects 💠

+

💠 Simple logos for complex projects. 💠

-# 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 - -

- -

- - -# Color schemes - -### Color scheme 1 - adi1090x's color scheme - -

- -

- -### Color scheme 2 - Cherry - -

- -

- -### Color scheme 3 - Midnight Abyss - -

- -

+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 index 87c8cae..dcc143a 100644 --- 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 deleted file mode 100644 index d349a38..0000000 --- a/docs/src/available-styles.md +++ /dev/null @@ -1,3 +0,0 @@ -::: warning WORK IN PROGRESS -The documentation will be completed soon. -::: diff --git a/assets/color1.png b/docs/src/available-styles/color1.png similarity index 100% rename from assets/color1.png rename to docs/src/available-styles/color1.png diff --git a/assets/color2.png b/docs/src/available-styles/color2.png similarity index 100% rename from assets/color2.png rename to docs/src/available-styles/color2.png diff --git a/assets/color3.png b/docs/src/available-styles/color3.png similarity index 100% rename from assets/color3.png rename to docs/src/available-styles/color3.png diff --git a/docs/src/available-styles/index.md b/docs/src/available-styles/index.md new file mode 100644 index 0000000..9bb4625 --- /dev/null +++ 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 b/docs/src/available-styles/style1.png similarity index 100% rename from assets/style1.png rename to docs/src/available-styles/style1.png diff --git a/docs/src/pull-request.md b/docs/src/pull-request.md new file mode 100644 index 0000000..94cc249 --- /dev/null +++ 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 new file mode 100644 index 0000000..ad329dc --- /dev/null +++ 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.