Merge pull request #78 from SkwalExe/docs

Finish "contributing" module in documentation, and update readme
SkwalExe · Aug 4, 2024 · 65f3cb7 · 65f3cb7
2 parents 097b03b + 5178355
commit 65f3cb7
Show file tree

Hide file tree

Showing 12 changed files with 605 additions and 145 deletions.
diff --git a/README.md b/README.md
@@ -13,6 +13,10 @@
 
 <p align="center">💠 Terminal based fractal explorer, including Mandelbrot, Burning Ship, and Julia. 💠</p>
 
+# Documentation ✨
+
+[**✨ --> Please head over to our documentation for more information! <-- ✨**](https://fractalistic.skwal.net)
+
 # Fractalistic
 
 <p align="center">
@@ -23,10 +27,10 @@
 
 You can install fractalistic easily with pip:
 ```bash
-python3 -m pip install fractalistic
+pip install fractalistic
 ```
 
-If you want to install the application securely, in an isolated environment, you can use [pipx](https://pypa.github.io/pipx/):
+If you want to install the application in an isolated environment, you can use [pipx](https://pypa.github.io/pipx/):
 ```bash
 pipx install fractalistic
 ```
@@ -36,128 +40,29 @@ Now start the program with:
 fractalistic
 ```
 
-> [!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.
+> [!INFO]
+> 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 and **opening a new shell session**.
 
 ```bash
 # For bash
-echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
-
+echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc; bash
 # For zsh
-echo 'export PATH=$PATH:~/.local/bin' >> ~/.zshrc
+echo 'export PATH=$PATH:~/.local/bin' >> ~/.zshrc; zsh
 ```
 
 # Features 🌟
-
-**Available fractals**:
-- Mandelbrot set
-- Burning Ship set
-- Every Julia sets
-
----
-
-- 🖥️ Terminal based
-- ✨ Next-gen Terminal UI with texutal
-- 🔍 Zoom in/out
-- 🚶 Move around
-- ⚙️ Change max iterations
-- 🎨 Change color palette
-- 🔢 Custom decimal precision
-- 📸 High definition screenshots
-- 📜 Save and load state
-- 📊 Show average divergence
-- 📌 Click to show coordinates and divergence
-- 🏃 Multithreaded rendering
-
-# Roadmap
-
-Possible features to add later:
-- [ ] Splash screen
-- [ ] New mandelbrot variants
-
-Commands:
-- [ ] Command to show current pos, zoom, etc
-
-# How to migrate your state files to >= 2.0.0
-
-First open your toml state file in a text editor. 
-You can open the screen position in the app by using the `pos` command, and copy/pasting the real and imaginary values.
-Then, select the correct fractal, color palette, precision and max_iter values in the app, 
-and use the `save_state` command to save your updated state file.
-
-# Development 
-
-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. If you want to contribute, open an empty pull request and explain what you want to do, wait for me to approve it and then you can start working on it.
-
-### Development environment
-
-**For this project, I recomment using vscode with Flake8 (linting/type-checking).**
-
-You will need to fork this repo and clone it locally. 
-
-```bash
-# Replace SkwalExe with your github username
-git clone https://github.com/SkwalExe/fractalistic
-cd fractalistic
-```
-
-Then, install the project and the dependencies locally 
-
-```bash
-pip install .
-```
-
-### Running the app in textual dev mode
-
-- First, open a textual console in a terminal with this command.
-
-```
-textual console
-```
-
-You will need to have `textual-dev` installed. You can install it with pip.
-
-```
-pip install textual-dev
-```
-
-- You can now open a new terminal, and start `fractalistic` in textual dev mode with :
-
-```bash
-# You must already be cd-ed into the repo directory
-TEXTUAL=devtools,debug python3 -m fractalistic
-```
-
-You will be able to see the app logs, and print to the textual console with the `textual.log` function.
-
-### Creating a pull request
-
-- First, create a new branch with a name that describes your feature/fix.
-
-```bash
-git checkout -b my-new-feature
-```
-
-**You can now start working on your feature/fix.**
-
-- Before commiting, you should run the linter and type-checker to make sure your code is clean.
-
-```bash
-# 'pip install flake8' if you don't have it
-flake8 fractalistic
-```
-
-**If you get any error, you should fix it before commiting.**
-
-- Now, commit your changes and push them to your fork.
-
-```bash
-git add .
-git commit -m "My new feature"
-git push origin my-new-feature
-```
-
-- Finally, open a pull request on github from your fork's page. I should receive a notification and I will review your changes.
+### **⚡ Multi-threaded**
+Fractalistic leverages parallel processing for complex arithmetic operations, enabling smooth navigation and rapid rendering.
+### **🔢 High Precision Arithmetics**
+Using MPFR and GMPY2, Fractalistic allows you to explore fractals infinitely deep by enabling users to increase the decimal precision for calculations as needed.
+### **📸 High Quality Screenshots**
+Fractalistic not only allows you to explore fractals at terminal resolution but also lets you generate high-resolution captures of your current view.
+### **✨ Next-gen Terminal User Interface**
+Fractalistic utilizes modern libraries such as Will McGugan's Textual framework to provide a full-featured navigation experience, all this in your classic terminal. Fractalistic also supports customizable mouse inputs, allowing for seemless navigation.
+### **📌 Robust Command System**
+Fractalistic offers a robust command system that goes beyond simple fractal navigation. Additional features include capturing high-definition screenshots, adjusting render settings, modifying navigation preferences, changing colors, and much more.
+### **⚙️  Modular Rendering Engine**
+Fractalistic's underlying rendering engine is highly modular. The integrated command system enables you to inspect and modify technical parameters, allowing you to explore beyond the basic Mandelbrot and Julia sets. The combination of adjustable parameters makes the number of possible fractals effectively infinite.
 
 # Screenshots
 
@@ -187,4 +92,4 @@ git push origin my-new-feature
 
 ![Screenshot 12](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot12.png)
 
-![Screenshot 13](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot13.png)
+![Screenshot 13](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot13.png)
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -38,6 +38,15 @@ export default defineConfig({
                 items: [
                     { text: '💎 General Presentation', link: '/presentation' },
                 ]
+            },
+            {
+                text: 'Development',
+                items: [
+                    { text: '🫂 Contributing', link: '/contributing' },
+                    { text: '✅ Recommended IDE setup', link: '/recommended-ide-setup' },
+                    { text: '🏗️ Project setup', link: '/project-setup' },
+                    { text: '🩷 Creating a pull request', link: '/creating-a-pull-request' },
+                ]
             }
         ],
 

diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -0,0 +1,18 @@
+# Contributing 🫂
+
+### You found a bug, or you need help 🆘
+
+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.
+You can also open an issue if you need help, I will always be happy to help someone interested in my projects!
+
+[You can open an issue on the project's Github repository. 🐙](https://github.com/SkwalExe/fractalistic/issues)
+
+### You want to contribute 🧑‍💻
+
+If you want to contribute, **open an empty pull request and explain what you want to do first.**
+Then, wait for me to approve it and then you can start working on it.
+This is very important, it is always heart-breaking to reject a pull 
+request that someone has invested a lot of time and efforts into. 🙁
+
+[You can create a pull request on the Github repository of the project. 🐙](https://github.com/SkwalExe/fractalistic/pulls)
+
diff --git a/docs/src/creating-a-pull-request.md b/docs/src/creating-a-pull-request.md
@@ -0,0 +1,33 @@
+# Creating a pull request 🩷
+
+When you finish your changes, you can then start to prepare your pull request.
+
+First, check for any formatting and linting errors.
+
+```bash
+pdm run lint
+pdm run format
+```
+
+After that, check for type errors.
+
+```bash
+pdm run check-types
+```
+
+Any problem that wasn't automatically corrected must be fixed manually before creating your pull request. If everything is OK, you can commit your changes to your own fork.
+
+```bash
+git add --all 
+git commit -m "My new feature"
+git push origin main
+```
+
+And finally, from your fork's repository, you can now open a new pull request. 
+I should receive a notification and I will review your changes!
+
+![Creating a pull request](./pr.png)
+
+#### **Thank you for making it this far—your contribution means the world to me, and I can't express how happy it makes me. If you're just reading the documentation and haven't contributed yet, thank you for your interest in this project. 🩷**
+
+![Kiss!!](./kiss.gif)
diff --git a/docs/src/devmode.png b/docs/src/devmode.png
diff --git a/docs/src/kiss.gif b/docs/src/kiss.gif
diff --git a/docs/src/pr.png b/docs/src/pr.png
diff --git a/docs/src/project-setup.md b/docs/src/project-setup.md
@@ -0,0 +1,39 @@
+# Project setup 🏗️ {#projec-setup}
+
+Before you start programming, you must setup the project locally.
+
+First, you will need to [**fork**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [Github repository](https://github.com/SkwalExe/fractalistic), and clone it.
+
+```bash
+# Replace SkwalExe with your github username
+git clone https://github.com/SkwalExe/fractalistic
+cd fractalistic
+```
+
+> [PDM](https://pdm-project.org/en/latest/) is used as a package manager for the project. \
+> If you need to install it, you can do so as follows on Linux systems:
+>
+>    ```bash
+>    curl -sSL https://pdm-project.org/install-pdm.py | python3 -
+>    ```
+
+Then, install the project and the dependencies.
+
+```bash
+pdm install
+```
+
+You can now start to make changes!
+
+### Running the app
+
+Since Fractalistic uses a TUI (GUI-like interface but in the terminal) you cannot use `print()` statements.
+
+You will need to open 2 separate terminals. 
+In the first one run `pdm console`, and in the second one, run `pdm run dev`. 
+
+This will open the app in **dev mode**, allowing you to log messages 
+to the **Textual console** (first terminal). To log messages within the code, 
+you must use the `textual.log()` function, and import it if needed. (`from textual import log`)
+
+![Dev mode preview](./devmode.png)
diff --git a/docs/src/recommended-ide-setup.md b/docs/src/recommended-ide-setup.md
@@ -0,0 +1,38 @@
+# Recommended IDE Setup ✅ {#recommended-setup}
+
+Writing code is good, but writing code with the assistance of autocomplete, 
+autoformatting, error notifications, and linting is even better. ✨
+
+![Example of type checking integration](./type-checking.png)
+
+You are not required to use the tools mentioned below in your IDE. 
+However, keep in mind that once you finish your changes, 
+**your code must still conform to the project's quality standards.**
+
+::: tip No worries 💫
+You will be able to detect and correct errors automatically with the help of predefined PDM scripts, 
+even if you don't use any of the IDE integrations presented below.
+
+This will be covered in a later section.
+:::
+
+
+### Linting and formatting 🦀 {#linting-and-formatting}
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting within our codebase.
+It is recommended that you install an extension for this tool, to benefit from automatic linting and formatting.
+
+- [Github repo for Ruff](https://github.com/astral-sh/ruff)
+- [LSP for Ruff (Neovim, Sublime Text...)](https://github.com/astral-sh/ruff-lsp)
+- [VSCode integration for Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
+
+### Type checking 👮 {#type-checking}
+
+[Pyright](https://github.com/microsoft/pyright) is used for static type checking,
+enabling us to detect errors during coding instead of at runtime. 
+It can also identify rare errors that would otherwise be time-consuming to diagnose. 
+Installing an IDE extension for Pyright is recommended to receive notifications whenever an error is detected.
+
+- [Github repo for Pyright](https://github.com/microsoft/pyright)
+- [For Neovim, you can use nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)
+- [VSCode integration for Pyright](https://marketplace.visualstudio.com/items?itemName=ms-pyright.pyright)
diff --git a/docs/src/type-checking.png b/docs/src/type-checking.png