diff --git a/README.md b/README.md index fbea3fe7..567da921 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@

- + readme-ai-banner-logo

-
README-AI, Your AI-Powered Documentation Assistant

Designed for simplicity, customization, and developer productivity.

@@ -27,45 +26,32 @@ ## ๐Ÿ”— Quick Links -1. [โšก๏ธ Introduction](#๏ธ-introduction) -2. [๐Ÿ‘พ Demo](#-demo) -3. [โ˜„๏ธ Features](#-features) -4. [๐Ÿ›ธ Quickstart](#-getting-started) -5. [๐Ÿ”ก Configuration](#-configuration) -6. [๐Ÿค– Examples](#-examples) -7. [๐Ÿ”ฐ Contributing](#-contributing) - -
+1. [Overview](#-overview) +2. [Demo](#-demo) +3. [Features](#-features) +4. [Getting Started](#-getting-started) +5. [Configuration](#-configuration) +6. [Examples](#-examples) +7. [Contributing](#-contributing) > [!IMPORTANT] -> โœจ See the [Official Documentation](https://eli64s.github.io/readme-ai) for more details. - - +> โœจ Visit the [Official Documentation][mkdocs] for detailed guides and tutorials. --- -## โšก๏ธ Introduction +## ๐Ÿ”ฎ Overview -***Objective*** +README-AI is a developer tool that automatically generates README markdown files using a robust repository processing engine and advanced language models. Simply provide a URL or path to your codebase, and a well-structured and detailed README will be generated. -README-AI is a developer tool for automatically generating README markdown files using a robust repository processor engine and generative AI. Simply provide a repository URL or local path to your codebase, and a well-structured and detailed README file will be generated for you. +**Why README-AI?** +This tool is designed to streamline the documentation process for developers, saving time and effort while ensuring high-quality README files. Key benefits include: -***Motivation*** - -This project aims to streamline the documentation process for developers, ensuring projects are properly documented and easy to understand. Whether you're working on an open-source project, enterprise software, or a personal project, README-AI is here to help you create high-quality documentation quickly and efficiently. +- **AI-Powered:** Leverage language models for intelligent content generation. +- **Consistency:** Ensure clean, standardized documentation across projects. +- **Customization:** Tailor the output to fit your project's requirements. +- **Language Agnostic:** Works with most programming languages/frameworks. +- **Save Time:** Generate comprehensive READMEs in less than a minute. --- @@ -83,88 +69,122 @@ This project aims to streamline the documentation process for developers, ensuri ## โ˜„๏ธ Features -* **Automated Documentation**: Synchronize data from third-party sources and generates documentation automatically. -* **Customizable Output**: Dozens of options for styling/formatting, badges, header designs, and more. -* **Language Agnostic**: Works across a wide range of programming languages and project types. -* **Multi-LLM Support**: Compatible with `OpenAI`, `Ollama`, `Anthropic`, `Google Gemini` and `Offline Mode`. -* **Offline Mode**: Generate a boilerplate README without calling an external API. -* **Markdown Best Practices**: Leverage best practices in Markdown formatting for clean, professional-looking docs. +- **๐Ÿš€ Automated Documentation:** Generate comprehensive README files automatically from your codebase. +- **๐ŸŽจ Customizable Output:** Tailor the styling, formatting, badges, header designs, and more preferences. +- **๐ŸŒ Language Agnostic:** Compatible with a wide range of programming languages and project types. +- **๐Ÿค– Multi-LLM Support:** Current support for `OpenAI`, `Ollama`, `Anthropic`, `Google Gemini`. +- **๐Ÿ“‘ Offline Mode:** Create boilerplate README files offline, without any external API calls. +- **๐Ÿ“ Best Practices:** Ensures clean, professional documentation, adhering to markdown best practices. -A few combinations of README styles and configurations: +Let's take a look at some possible customizations created by readme-ai: - + - + - + + + + + - + + - - + - + - + + + + + +
- custom-project-logo
+ custom-dragon-project-logo +
--image custom --badge-color FF4B4B --badge-style flat-square --header-style classic

-
+ compact-readme-header +
--image cloud --header-style compact --toc-style fold

+ svg- +
+ --badge-style for-the-badge --header-style svg +
- cloud-db-logo
+ readme-header-with-cloud-logo +
--align left --badge-style flat-square --image cloud 		- gradient-markdown-logo
+ readme-header-with-gradient-markdown-logo +
--align left --badge-style flat --image gradient
- custom-logo
+ custom-balloon-project-logo +
--badge-style flat --image custom 		- skills-light
+ readme-header-with-skill-icons-light +
--badge-style skills-light --image grey
- readme-ai-header
+ readme-header-with-blue-markdown-logo +
--badge-style flat-square 		- black-logo
+ readme-header-with-black-readme-logo +
--badge-style flat --image black
- default-header
+ custom-database-project-logo +
--image custom --badge-color 00ffe9 --badge-style flat-square --header-style classic
- default-header
+ llm-generated-project-logo +
--image llm --badge-style plastic --header-style classic
- default-header
+ readme-header-style-modern +
--image custom --badge-color BA0098 --badge-style flat-square --header-style modern --toc-style fold
+ ascii-readme-header-style +
+ --header-style ascii + 		+ ascii-box-readme-header-style +
+ --header-style ascii_box +
See the Configuration section for a complete list of CLI options. +**Additional Generated Sections:** +
๐Ÿ“ Overview
@@ -176,7 +196,8 @@ See the llm-overview +
readme-overview-section +
@@ -186,12 +207,13 @@ See the prompt template. +

โ—Ž Generated markdown table that highlights the key technical features and components of the codebase. This table is generated using a structured prompt template.

- llm-features + readme-features-section + @@ -207,7 +229,7 @@ See the - directory-tree + directory-tree @@ -219,7 +241,7 @@ See the - file-summaries + file-summaries @@ -235,7 +257,7 @@ See the prerequisites + getting-started-section-prerequisites @@ -243,7 +265,7 @@ See the installation + getting-started-section-usage-and-testing @@ -262,7 +284,8 @@ See the contributing-guidelines + contributing-guidelines-section + Additional Sections
@@ -271,7 +294,7 @@ See the footer + footer-readme-section @@ -280,207 +303,220 @@ See the  Pip ```sh โฏ pip install readmeai ``` + + +###  Pipx ```sh โฏ pipx install readmeai ``` -> [! TIP] -> -> Use [pipx](https://pipx.pypa.io/stable/installation/) to install and run Python command-line applications without causing dependency conflicts with other packages! +> [!TIP] +> Using [pipx](https://pipx.pypa.io/stable/installation/) allows you to install and run Python command-line applications in isolated environments, which helps prevent dependency conflicts with other Python projects. + -```sh -โฏ docker pull zeroxeli/readme-ai:latest -``` - -#### From `source` - -
Build readme-ai
- -#### Using `bash` +###  Docker -[![bash](https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat&logo=GNU-Bash&logoColor=white)](https://www.gnu.org/software/bash/) +Pull the latest Docker image from the Docker Hub repository. ```sh -โฏ bash setup/setup.sh +โฏ docker pull zeroxeli/readme-ai:latest ``` -#### Using `poetry` +###  From source - [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) +
Click to expand instructions -1. Clone the repository: - -```sh -โฏ git clone https://github.com/eli64s/readme-ai -``` +1. **Clone the repository:** -2. Navigate to the `readme-ai` directory: + ```sh + โฏ git clone https://github.com/eli64s/readme-ai + ``` -```sh -โฏ cd readme-ai -``` +2. **Navigate to the `readme-ai` directory:** -3. Install dependencies using `poetry`: + ```sh + โฏ cd readme-ai + ``` -```sh -โฏ poetry install -``` +3. **Install dependencies:** -4. Enter the `poetry` shell environment: + ```sh + โฏ pip install -r setup/requirements.txt + ``` -```sh -โฏ poetry shell -``` +Alternatively, the project can be setup using the bash script below: -
+###  Bash -#### Installing Optional Dependencies +1. **Run the setup script:** -To use the **Anthropic** and **Google Gemini** clients, install the optional dependencies. + ```sh + โฏ bash setup/setup.sh + ``` -Anthropic: +Or, use `poetry` to build the project: -```sh -โฏ pip install readmeai[anthropic] -``` +###  Poetry -Google Gemini: +1. **Install dependencies using Poetry:** -```sh -โฏ pip install readmeai[gemini] -``` + ```sh + โฏ poetry install + ``` ---- +

-### โš™๏ธ Usage +> [!IMPORTANT] +> To use the **Anthropic** and **Google Gemini** clients, additional dependencies are required. See the following installation commands: +> - **Anthropic:** +> ```sh +> โฏ pip install "readmeai[anthropic]" +> ``` +> - **Google Gemini:** +> ```sh +> โฏ pip install "readmeai[google-generativeai]" +> ``` -#### Environment Variables +## ๐Ÿค– Running the CLI -**OpenAI** +**1. Set Up Environment Variables** -Generate a OpenAI API key and set it as the environment variable `OPENAI_API_KEY` . +With OpenAI: ```sh -# Using Linux or macOS โฏ export OPENAI_API_KEY= -# Using Windows +# Or for Windows users: + โฏ set OPENAI_API_KEY= ``` -**Ollama** +
Additional Providers (Ollama, Anthropic, Google Gemini)
-Pull your model of choice from the Ollama repository: +
Ollama
-```sh -โฏ ollama pull mistral:latest -``` +Refer to the [Ollama documentation](https://github.com/ollama/ollama) for more information on setting up the Ollama API. Here is a basic example: -Start the Ollama server: +1. Pull your model of choice from the Ollama repository: -```sh -โฏ export OLLAMA_HOST=127.0.0.1 && ollama serve -``` + ```sh + โฏ ollama pull mistral:latest + ``` -See all available models from Ollama [here.](https://github.com/ollama/ollama-python?tab=readme-ov-file) +2. Start the Ollama server and set the `OLLAMA_HOST` environment variable: -**Anthropic** + ```sh + โฏ export OLLAMA_HOST=127.0.0.1 && ollama serve + ``` -Generate an Anthropic API key and set the following environment variables: +
-```sh -โฏ export ANTHROPIC_API_KEY= -``` +
Anthropic -**Google Gemini** +With Anthropic: -Generate a Google API key and set the following environment variables: + ```sh + โฏ export ANTHROPIC_API_KEY= + ``` -```sh -โฏ export GOOGLE_API_KEY= -``` +
+
Google Gemini -#### Running the CLI +With Google Gemini: -#### Using `pip` + ```sh + โฏ export GOOGLE_API_KEY= -With OpenAI: +
+ +**2. Generate a README** + +Run the following command, replacing the repository URL with your own: ```sh -โฏ readmeai --api openai --repository https://github.com/eli64s/readme-ai +โฏ readmeai --repository https://github.com/eli64s/readme-ai --api openai ``` -> [! IMPORTANT] +> [!IMPORTANT] > By default, the `gpt-3.5-turbo` model is used. Higher costs may be incurred when more advanced models. > -With Ollama: +Run with `Ollama` and set `llama3` as the model: ```sh โฏ readmeai --api ollama --model llama3 --repository https://github.com/eli64s/readme-ai ``` -With Anthropic: +Run with `Anthropic`: ```sh โฏ readmeai --api anthropic -m claude-3-5-sonnet-20240620 -r https://github.com/eli64s/readme-ai ``` - -With Gemini: +Run with `Google Gemini`: ```sh โฏ readmeai --api gemini -m gemini-1.5-flash -r https://github.com/eli64s/readme-ai ``` -Adding more customization options: +Use a `local` directory path: + +```sh +readmeai --repository /path/to/your/project +``` + +Add more customization options: ```sh โฏ readmeai --repository https://github.com/eli64s/readme-ai \ @@ -497,76 +533,91 @@ Adding more customization options: --emojis ``` -#### Using `docker` - -Running the Docker container with the OpenAI API: +###  Docker -[![docker](https://img.shields.io/badge/Docker-2496ED.svg?style=flat&logo=Docker&logoColor=white)](https://hub.docker.com/r/zeroxeli/readme-ai) +Run the Docker container with the OpenAI client: ```sh -โฏ docker run -it \ --e OPENAI_API_KEY=$OPENAI_API_KEY \ --v "$(pwd)":/app zeroxeli/readme-ai:latest \ --r https://github.com/eli64s/readme-ai +โฏ docker run -it --rm \ + -e OPENAI_API_KEY=$OPENAI_API_KEY \ + -v "$(pwd)":/app zeroxeli/readme-ai:latest \ + -r https://github.com/eli64s/readme-ai \ + --api openai ``` -#### Using `streamlit` +###  From source -Try readme-ai directly in your browser, no installation required. See the readme-ai-streamlit repository for more details. +
Click to expand instructions -[](https://readme-ai.streamlit.app/) +###  Bash -#### From `source` +If you installed the project from source with the bash script, run the following command: -
- Using readme-ai
+1. **Activate the virtual environment:** - #### Using `bash` + ```sh + โฏ conda activate readmeai + ``` - [![bash](https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat&logo=GNU-Bash&logoColor=white)](https://www.gnu.org/software/bash/) +2. **Run the CLI:** + ```sh + โฏ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai + ``` +###  Poetry -```sh - โฏ conda activate readmeai - โฏ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai - ``` +1. **Activate the virtual environment:** - #### Using `poetry` + ```sh + โฏ poetry shell + ``` - [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) +2. **Run the CLI:** + ```sh + โฏ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai + ``` +
-```sh - โฏ poetry shell - โฏ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai - ``` +###  Streamlit -
+Try readme-ai directly in your browser, no installation required. See the readme-ai-streamlit repository for more details. ---- +[](https://readme-ai.streamlit.app/) -### ๐Ÿงช Testing +--- -The pytest framework and nox automation tool are used for testing the application. +## ๐Ÿงช Testing + + +The [pytest](https://docs.pytest.org/en/7.2.x/contents.html) and [nox](https://nox.thea.codes/en/stable/) frameworks are used for development and testing. + +Install the dependencies using Poetry: + +```sh +โฏ poetry install --with dev,test +``` + +Run the unit test suite using Pytest: ```sh โฏ make test ``` -#### Using `nox` +Run the test suite against Python 3.9, 3.10, 3.11, and 3.12 using Nox: ```sh โฏ make test-nox ``` > [!TIP] -> Use [nox](https://nox.thea.codes/en/stable/) to test application against multiple Python environments and dependencies! +> Nox is an automation tool that automates testing in multiple Python environments. It is used to ensure compatibility across different Python versions. --- @@ -574,37 +625,33 @@ The pytest framework and nox automation tool are used for testing the applicatio Customize your README generation using these CLI options: -| Option | Description | Default | -| :-- | :--: | :--: | -| `--align` | Text align in header | `center` | -| `--api` | LLM API service provider | `offline` | -| `--badge-color` | Badge color name or hex code | `0080ff` | -| `--badge-style` | Badge icon style type | `flat` | -| `--base-url` | Base URL for the repository | `v1/chat/completions` | -| `--context-window` | Maximum context window of the LLM API | `3900` | -| `--emojis` | Adds emojis to the README header sections | `False` | -| `--header-style` | Header template style | `classic` | -| `--image` | Project logo image | `blue` | -| `--model` | Specific LLM model to use | `gpt-3.5-turbo` | -| `--output` | Output filename | `readme-ai.md` | -| `--rate-limit` | Maximum API requests per minute | `10` | -| `--repository` | Repository URL or local directory path | `None` | -| `--temperature` | Creativity level for content generation | `0.1` | -| `--toc-style` | Table of contents template style | `bullet` | -| `--top-p` | Probability of the top-p sampling method | `0.9` | -| `--tree-depth` | Maximum depth of the directory tree structure | `2` | +| Option | Description | Default | +|-------------------|-----------------------------------------------|-------------------| +| `--align` | Text alignment in header | `center` | +| `--api` | LLM API service provider | `offline` | +| `--badge-color` | Badge color name or hex code | `0080ff` | +| `--badge-style` | Badge icon style type | `flat` | +| `--header-style` | Header template style | `classic` | +| `--toc-style` | Table of contents style | `bullet` | +| `--emojis` | Adds emojis to the README header sections | `False` | +| `--image` | Project logo image | `blue` | +| `--model` | Specific LLM model to use | `gpt-3.5-turbo` | +| `--output` | Output filename | `readme-ai.md` | +| `--repository` | Repository URL or local directory path | `None` | +| `--temperature` | Creativity level for content generation | `0.1` | +| `--tree-depth` | Maximum depth of the directory tree structure | `2` | + +For a full list of options, run: -> [!TIP] -> For a full list of options, run `readmeai --help` in your terminal. -> - -### ๐ŸŽจ Customization +```sh +readmeai --help +``` -To see the full list of customization options, check out the [Configuration](https://eli64s.github.io/readme-ai/configuration/) section in the official documentation. This section provides a detailed overview of all available CLI options and how to use them, including badge styles, header templates, and more. +Visit the [Official Documentation][mkdocs] for more detailed information on configuration options, examples, and best practices. --- -## ๐Ÿค– Examples +## ๐ŸŽจ Examples | Language/Framework | Output File | Input Repository | Description | | :--: | :--: | :--: | :--: | @@ -620,11 +667,11 @@ To see the full list of customization options, check out the [Configuration](htt | Jupyter Notebook | [readme-mlops.md][9a] | [mlops-course][9b] | MLOps course repository | | Apache Flink | [readme-local.md][10a] | Local Directory | Example using a local directory | -See additional README files generated by readme-ai [here](https://github.com/eli64s/readme-ai/tree/main/examples/markdown) +Find more examples [here](https://github.com/eli64s/readme-ai/tree/main/examples). --- -## ๐ŸŽ๐Ÿ’จ Project Roadmap +## ๐ŸŽ๐Ÿ’จ Roadmap * [ ] Release `readmeai 1.0.0` with enhanced documentation management features. * [ ] Develop `Vscode Extension` to generate README files directly in the editor. @@ -636,11 +683,11 @@ To see the full list of customization options, check out the [Configuration](htt ## ๐Ÿ”ฐ Contributing -Contributions are welcome and encouraged! If interested, please begin by reviewing the resources below: +Contributions are welcome! Please read the [Contributing Guide][contributing] to get started. -* **๐Ÿ’ก [Contributing Guide][1]**: Learn about our contribution process, coding standards, and how to submit your ideas. -* **๐Ÿ’ฌ [Start a Discussion][2]**: Have questions or suggestions? Join our community discussions to share your thoughts and engage with others. -* **๐Ÿ› [Report an Issue][3]**: Found a bug or have a feature request? Let us know by opening an issue so we can address it promptly. +- **๐Ÿ’ก [Contributing Guide][contributing]**: Learn about our contribution process and coding standards. +- **๐Ÿ› [Report an Issue][issues]**: Found a bug? Let us know! +- **๐Ÿ’ฌ [Start a Discussion][discussions]**: Have ideas or suggestions? We'd love to hear from you.

@@ -651,32 +698,34 @@ Contributions are welcome and encouraged! If interested, please begin by reviewi --- -## ๐Ÿ“’ Changelog - -[Changelog][0] - ---- - ## ๐ŸŽ— License -[MIT License][4] +README-AI is released under the terms of the [MIT License][license]. --- ## ๐Ÿ™Œ Acknowledgments * [Shields.io](https://shields.io/) +* [Simple Icons](https://simpleicons.org/) * [Aveek-Saha/GitHub-Profile-Badges](https://github.com/Aveek-Saha/GitHub-Profile-Badges) * [Ileriayo/Markdown-Badges](https://github.com/Ileriayo/markdown-badges) * [tandpfun/skill-icons](https://github.com/tandpfun/skill-icons) -

- โฌ†๏ธ Top -

+

โฌ†๏ธ Top

--- - + +[overview]: #-overview "๐Ÿ”ฎ Overview" +[demo]: (#-demo) "๐Ÿ‘พ Demo" +[features]: (#-features) "โ˜„๏ธ Features" +[getting-started]: (#-getting-started) "๐Ÿ›ธ Getting Started" +[configuration]: (#-configuration) "๐Ÿ”ก Configuration" +[examples]: (#-examples) "๐ŸŽจ Examples" +[contributing]: (#-contributing) "๐Ÿ”ฐ Contributing" + + [0a]: https://github.com/eli64s/readme-ai/blob/main/examples/readme-ai.md "readme-python.md" [0b]: https://github.com/eli64s/readme-ai "readme-ai" [1a]: https://github.com/eli64s/readme-ai/blob/main/examples/readme-typescript.md "readme-typescript.md" @@ -699,9 +748,11 @@ Contributions are welcome and encouraged! If interested, please begin by reviewi [9b]: https://github.com/GokuMohandas/mlops-course "mlops-course" [10a]: https://github.com/eli64s/readme-ai/blob/main/examples/readme-local.md "readme-local.md" - -[0]: https://github.com/eli64s/readme-ai/blob/main/CHANGELOG.md "Changelog" -[1]: https://github.com/eli64s/readme-ai/blob/main/CONTRIBUTING.md "Contributing Guide" -[2]: https://github.com/eli64s/readme-ai/discussions "Start a Discussion" -[3]: https://github.com/eli64s/readme-ai/issues "Open an Issue" -[4]: https://github.com/eli64s/readme-ai/blob/main/LICENSE "License" + +[contributing]: https://github.com/eli64s/readme-ai/blob/main/CONTRIBUTING.md +[issues]: https://github.com/eli64s/readme-ai/issues +[discussions]: https://github.com/eli64s/readme-ai/discussions +[license]: https://github.com/eli64s/readme-ai/blob/main/LICENSE + + +[mkdocs]: https://eli64s.github.io/readme-ai "Official Documentation" diff --git a/docs/assets/icons/anthropic.svg b/docs/assets/icons/anthropic.svg new file mode 100644 index 00000000..3408b26e --- /dev/null +++ b/docs/assets/icons/anthropic.svg @@ -0,0 +1 @@ +Anthropic diff --git a/docs/assets/icons/docker-color.svg b/docs/assets/icons/docker-color.svg new file mode 100644 index 00000000..c2cad332 --- /dev/null +++ b/docs/assets/icons/docker-color.svg @@ -0,0 +1 @@ +Docker diff --git a/docs/assets/icons/docker.svg b/docs/assets/icons/docker.svg new file mode 100644 index 00000000..b8a5f2cc --- /dev/null +++ b/docs/assets/icons/docker.svg @@ -0,0 +1 @@ +Docker diff --git a/docs/assets/icons/git-color.svg b/docs/assets/icons/git-color.svg new file mode 100644 index 00000000..82ccecae --- /dev/null +++ b/docs/assets/icons/git-color.svg @@ -0,0 +1 @@ +Git diff --git a/docs/assets/icons/git.svg b/docs/assets/icons/git.svg new file mode 100644 index 00000000..ba626c44 --- /dev/null +++ b/docs/assets/icons/git.svg @@ -0,0 +1 @@ +Git diff --git a/docs/assets/icons/gnubash-color.svg b/docs/assets/icons/gnubash-color.svg new file mode 100644 index 00000000..6dfa3152 --- /dev/null +++ b/docs/assets/icons/gnubash-color.svg @@ -0,0 +1 @@ +GNU Bash diff --git a/docs/assets/icons/gnubash.svg b/docs/assets/icons/gnubash.svg new file mode 100644 index 00000000..053771f6 --- /dev/null +++ b/docs/assets/icons/gnubash.svg @@ -0,0 +1 @@ +GNU Bash diff --git a/docs/assets/icons/googlegemini.svg b/docs/assets/icons/googlegemini.svg new file mode 100644 index 00000000..60197dc4 --- /dev/null +++ b/docs/assets/icons/googlegemini.svg @@ -0,0 +1 @@ +Google Gemini diff --git a/docs/assets/icons/ollama.svg b/docs/assets/icons/ollama.svg new file mode 100644 index 00000000..1c0ab7b6 --- /dev/null +++ b/docs/assets/icons/ollama.svg @@ -0,0 +1 @@ +Ollama diff --git a/docs/assets/icons/openai.svg b/docs/assets/icons/openai.svg new file mode 100644 index 00000000..7d9d324e --- /dev/null +++ b/docs/assets/icons/openai.svg @@ -0,0 +1 @@ +OpenAI diff --git a/docs/assets/icons/pipx-color.svg b/docs/assets/icons/pipx-color.svg new file mode 100644 index 00000000..716acfb9 --- /dev/null +++ b/docs/assets/icons/pipx-color.svg @@ -0,0 +1 @@ +pipx diff --git a/docs/assets/icons/pipx.svg b/docs/assets/icons/pipx.svg new file mode 100644 index 00000000..8f942eeb --- /dev/null +++ b/docs/assets/icons/pipx.svg @@ -0,0 +1 @@ +pipx diff --git a/docs/assets/icons/poetry-color.svg b/docs/assets/icons/poetry-color.svg new file mode 100644 index 00000000..7edc244f --- /dev/null +++ b/docs/assets/icons/poetry-color.svg @@ -0,0 +1 @@ +Poetry diff --git a/docs/assets/icons/poetry.svg b/docs/assets/icons/poetry.svg new file mode 100644 index 00000000..a158c6d2 --- /dev/null +++ b/docs/assets/icons/poetry.svg @@ -0,0 +1 @@ +Poetry diff --git a/docs/assets/icons/pypi-color.svg b/docs/assets/icons/pypi-color.svg new file mode 100644 index 00000000..0dd96bb1 --- /dev/null +++ b/docs/assets/icons/pypi-color.svg @@ -0,0 +1 @@ +PyPI diff --git a/docs/assets/icons/pypi.svg b/docs/assets/icons/pypi.svg new file mode 100644 index 00000000..2207e4d2 --- /dev/null +++ b/docs/assets/icons/pypi.svg @@ -0,0 +1 @@ +PyPI diff --git a/docs/assets/icons/pytest-color.svg b/docs/assets/icons/pytest-color.svg new file mode 100644 index 00000000..2fbdb474 --- /dev/null +++ b/docs/assets/icons/pytest-color.svg @@ -0,0 +1 @@ +Pytest diff --git a/docs/assets/icons/pytest.svg b/docs/assets/icons/pytest.svg new file mode 100644 index 00000000..76597a75 --- /dev/null +++ b/docs/assets/icons/pytest.svg @@ -0,0 +1 @@ +Pytest diff --git a/docs/assets/icons/python-color.svg b/docs/assets/icons/python-color.svg new file mode 100644 index 00000000..fc9eb00f --- /dev/null +++ b/docs/assets/icons/python-color.svg @@ -0,0 +1 @@ +Python diff --git a/docs/assets/icons/python.svg b/docs/assets/icons/python.svg new file mode 100644 index 00000000..297a11e0 --- /dev/null +++ b/docs/assets/icons/python.svg @@ -0,0 +1 @@ +Python diff --git a/docs/assets/icons/readme-ai-banner.svg b/docs/assets/icons/readme-ai-banner.svg new file mode 100644 index 00000000..12d1d2f6 --- /dev/null +++ b/docs/assets/icons/readme-ai-banner.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + readme-ai + + + Your AI-Powered Documentation Assistant + + + + + + + + M + + + + + + + + + + + + diff --git a/docs/assets/icons/readme-ai-logo-animated.svg b/docs/assets/icons/readme-ai-logo-animated.svg new file mode 100644 index 00000000..d4a79635 --- /dev/null +++ b/docs/assets/icons/readme-ai-logo-animated.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + M + + + + + + + + README-AI + + + + + + + + + + + + + diff --git a/docs/assets/icons/readme-ai-logo.svg b/docs/assets/icons/readme-ai-logo-gradient.svg similarity index 100% rename from docs/assets/icons/readme-ai-logo.svg rename to docs/assets/icons/readme-ai-logo-gradient.svg diff --git a/docs/assets/icons/readme-ai-logo-simple.svg b/docs/assets/icons/readme-ai-logo-simple.svg new file mode 100644 index 00000000..17a58074 --- /dev/null +++ b/docs/assets/icons/readme-ai-logo-simple.svg @@ -0,0 +1,62 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + readme-ai + + + Your AI-Powered Documentation Assistant + + + + + + + diff --git a/docs/assets/icons/readme.svg b/docs/assets/icons/readme-logo-purple.svg similarity index 100% rename from docs/assets/icons/readme.svg rename to docs/assets/icons/readme-logo-purple.svg diff --git a/docs/assets/icons/streamlit-color.svg b/docs/assets/icons/streamlit-color.svg new file mode 100644 index 00000000..4c331bda --- /dev/null +++ b/docs/assets/icons/streamlit-color.svg @@ -0,0 +1 @@ +Streamlit diff --git a/docs/assets/icons/streamlit.svg b/docs/assets/icons/streamlit.svg new file mode 100644 index 00000000..f4b34348 --- /dev/null +++ b/docs/assets/icons/streamlit.svg @@ -0,0 +1 @@ +Streamlit diff --git a/docs/assets/images/contributing_guidelines.png b/docs/assets/images/contributing/contributing-guidelines.png similarity index 100% rename from docs/assets/images/contributing_guidelines.png rename to docs/assets/images/contributing/contributing-guidelines.png diff --git a/docs/assets/images/footer.png b/docs/assets/images/contributing/footer.png similarity index 100% rename from docs/assets/images/footer.png rename to docs/assets/images/contributing/footer.png diff --git a/docs/assets/images/dalle/github-readme-quotes.png b/docs/assets/images/dalle/github-readme-quotes.png deleted file mode 100644 index 03fab33e..00000000 Binary files a/docs/assets/images/dalle/github-readme-quotes.png and /dev/null differ diff --git a/docs/assets/images/dalle/readme-ai-streamlit.png b/docs/assets/images/dalle/readme-ai-streamlit.png deleted file mode 100644 index 909d864c..00000000 Binary files a/docs/assets/images/dalle/readme-ai-streamlit.png and /dev/null differ diff --git a/docs/assets/images/directory-tree.png b/docs/assets/images/directory-tree.png deleted file mode 100644 index e7634465..00000000 Binary files a/docs/assets/images/directory-tree.png and /dev/null differ diff --git a/docs/assets/images/prerequisites.png b/docs/assets/images/getting-started/prerequisites-and-installation.png similarity index 100% rename from docs/assets/images/prerequisites.png rename to docs/assets/images/getting-started/prerequisites-and-installation.png diff --git a/docs/assets/images/usage_guide.png b/docs/assets/images/getting-started/usage-and-testing.png similarity index 100% rename from docs/assets/images/usage_guide.png rename to docs/assets/images/getting-started/usage-and-testing.png diff --git a/docs/assets/images/headers/ascii-box-toc-roman.png b/docs/assets/images/headers/ascii-box-toc-roman.png new file mode 100644 index 00000000..32ec99fd Binary files /dev/null and b/docs/assets/images/headers/ascii-box-toc-roman.png differ diff --git a/docs/assets/images/headers/ascii-box.png b/docs/assets/images/headers/ascii-box.png new file mode 100644 index 00000000..0604717c Binary files /dev/null and b/docs/assets/images/headers/ascii-box.png differ diff --git a/docs/assets/images/headers/ascii.png b/docs/assets/images/headers/ascii.png new file mode 100644 index 00000000..383ccf26 Binary files /dev/null and b/docs/assets/images/headers/ascii.png differ diff --git a/docs/assets/images/headers/header-black.png b/docs/assets/images/headers/black.png similarity index 100% rename from docs/assets/images/headers/header-black.png rename to docs/assets/images/headers/black.png diff --git a/docs/assets/images/headers/header-flat-square.png b/docs/assets/images/headers/blue.png similarity index 100% rename from docs/assets/images/headers/header-flat-square.png rename to docs/assets/images/headers/blue.png diff --git a/docs/assets/images/headers/header-toc-default.png b/docs/assets/images/headers/classic-no-emojis.png similarity index 100% rename from docs/assets/images/headers/header-toc-default.png rename to docs/assets/images/headers/classic-no-emojis.png diff --git a/docs/assets/images/headers/header-cloud.png b/docs/assets/images/headers/cloud.png similarity index 100% rename from docs/assets/images/headers/header-cloud.png rename to docs/assets/images/headers/cloud.png diff --git a/docs/assets/images/headers/header-minimal.png b/docs/assets/images/headers/compact.png similarity index 100% rename from docs/assets/images/headers/header-minimal.png rename to docs/assets/images/headers/compact.png diff --git a/docs/assets/images/headers/header-default-v2.png b/docs/assets/images/headers/custom-database.png similarity index 100% rename from docs/assets/images/headers/header-default-v2.png rename to docs/assets/images/headers/custom-database.png diff --git a/docs/assets/images/headers/custom-image.png b/docs/assets/images/headers/custom-dragon.png similarity index 100% rename from docs/assets/images/headers/custom-image.png rename to docs/assets/images/headers/custom-dragon.png diff --git a/docs/assets/images/project-logo-custom.png b/docs/assets/images/headers/custom.png similarity index 100% rename from docs/assets/images/project-logo-custom.png rename to docs/assets/images/headers/custom.png diff --git a/docs/assets/images/headers/header-custom.png b/docs/assets/images/headers/customn-balloon.png similarity index 100% rename from docs/assets/images/headers/header-custom.png rename to docs/assets/images/headers/customn-balloon.png diff --git a/docs/assets/images/project-logo-dalle.png b/docs/assets/images/headers/dalle.png similarity index 100% rename from docs/assets/images/project-logo-dalle.png rename to docs/assets/images/headers/dalle.png diff --git a/docs/assets/images/headers/header-default.png b/docs/assets/images/headers/default.png similarity index 100% rename from docs/assets/images/headers/header-default.png rename to docs/assets/images/headers/default.png diff --git a/docs/assets/images/headers/header-gradient.png b/docs/assets/images/headers/gradient.png similarity index 100% rename from docs/assets/images/headers/header-gradient.png rename to docs/assets/images/headers/gradient.png diff --git a/docs/assets/images/headers/header-mlops.png b/docs/assets/images/headers/mlops.png similarity index 100% rename from docs/assets/images/headers/header-mlops.png rename to docs/assets/images/headers/mlops.png diff --git a/docs/assets/images/headers/modern-pyflink.png b/docs/assets/images/headers/modern-flat-square.png similarity index 100% rename from docs/assets/images/headers/modern-pyflink.png rename to docs/assets/images/headers/modern-flat-square.png diff --git a/docs/assets/images/headers/modern-docker-go.png b/docs/assets/images/headers/modern-for-the-badge.png similarity index 100% rename from docs/assets/images/headers/modern-docker-go.png rename to docs/assets/images/headers/modern-for-the-badge.png diff --git a/docs/assets/images/headers/header-skills.png b/docs/assets/images/headers/skill-icons-light.png similarity index 100% rename from docs/assets/images/headers/header-skills.png rename to docs/assets/images/headers/skill-icons-light.png diff --git a/docs/assets/images/headers/header-skills-dark.png b/docs/assets/images/headers/skill-icons.png similarity index 100% rename from docs/assets/images/headers/header-skills-dark.png rename to docs/assets/images/headers/skill-icons.png diff --git a/docs/assets/images/headers/svg-banner.png b/docs/assets/images/headers/svg-banner.png new file mode 100644 index 00000000..433609ab Binary files /dev/null and b/docs/assets/images/headers/svg-banner.png differ diff --git a/docs/assets/images/llm-content/dalle/github-readme-quotes.png b/docs/assets/images/llm-content/dalle/github-readme-quotes.png new file mode 100644 index 00000000..276d345f Binary files /dev/null and b/docs/assets/images/llm-content/dalle/github-readme-quotes.png differ diff --git a/docs/assets/images/llm-content/dalle/readme-ai-bot.png b/docs/assets/images/llm-content/dalle/readme-ai-bot.png new file mode 100644 index 00000000..66f126b0 Binary files /dev/null and b/docs/assets/images/llm-content/dalle/readme-ai-bot.png differ diff --git a/docs/assets/images/llm-content/dalle/readme-ai-feather.png b/docs/assets/images/llm-content/dalle/readme-ai-feather.png new file mode 100644 index 00000000..e224cf86 Binary files /dev/null and b/docs/assets/images/llm-content/dalle/readme-ai-feather.png differ diff --git a/docs/assets/images/llm-content/dalle/readme-ai-streamlit.png b/docs/assets/images/llm-content/dalle/readme-ai-streamlit.png new file mode 100644 index 00000000..05067f1d Binary files /dev/null and b/docs/assets/images/llm-content/dalle/readme-ai-streamlit.png differ diff --git a/docs/assets/images/dalle/readme-ai.png b/docs/assets/images/llm-content/dalle/readme-ai.png similarity index 100% rename from docs/assets/images/dalle/readme-ai.png rename to docs/assets/images/llm-content/dalle/readme-ai.png diff --git a/docs/assets/images/dalle/readme-streamlit-dalle.png b/docs/assets/images/llm-content/dalle/readme-streamlit-dalle.png similarity index 100% rename from docs/assets/images/dalle/readme-streamlit-dalle.png rename to docs/assets/images/llm-content/dalle/readme-streamlit-dalle.png diff --git a/docs/assets/images/dalle/readme-streamlit-v0.5.88.png b/docs/assets/images/llm-content/dalle/readme-streamlit-v0.5.88.png similarity index 100% rename from docs/assets/images/dalle/readme-streamlit-v0.5.88.png rename to docs/assets/images/llm-content/dalle/readme-streamlit-v0.5.88.png diff --git a/docs/assets/images/dalle/thepipe.png b/docs/assets/images/llm-content/dalle/thepipe.png similarity index 100% rename from docs/assets/images/dalle/thepipe.png rename to docs/assets/images/llm-content/dalle/thepipe.png diff --git a/docs/assets/images/llm-content/dalle/thepipe_v2.png b/docs/assets/images/llm-content/dalle/thepipe_v2.png new file mode 100644 index 00000000..e0e8ed99 Binary files /dev/null and b/docs/assets/images/llm-content/dalle/thepipe_v2.png differ diff --git a/docs/assets/images/llm-features.png b/docs/assets/images/llm-content/features-table.png similarity index 100% rename from docs/assets/images/llm-features.png rename to docs/assets/images/llm-content/features-table.png diff --git a/docs/assets/images/llm-summaries.png b/docs/assets/images/llm-content/file-summaries.png similarity index 100% rename from docs/assets/images/llm-summaries.png rename to docs/assets/images/llm-content/file-summaries.png diff --git a/docs/assets/images/overview.png b/docs/assets/images/llm-content/overview.png similarity index 100% rename from docs/assets/images/overview.png rename to docs/assets/images/llm-content/overview.png diff --git a/docs/assets/images/file-summaries.png b/docs/assets/images/project-structure/file-summaries.png similarity index 100% rename from docs/assets/images/file-summaries.png rename to docs/assets/images/project-structure/file-summaries.png diff --git a/docs/assets/images/project-structure.png b/docs/assets/images/project-structure/tree.png similarity index 100% rename from docs/assets/images/project-structure.png rename to docs/assets/images/project-structure/tree.png diff --git a/docs/assets/images/quickstart.png b/docs/assets/images/quickstart.png deleted file mode 100644 index bdbac0bd..00000000 Binary files a/docs/assets/images/quickstart.png and /dev/null differ diff --git a/docs/assets/images/readme-ai-logo.png b/docs/assets/images/readme-ai-logo-gradient.png similarity index 100% rename from docs/assets/images/readme-ai-logo.png rename to docs/assets/images/readme-ai-logo-gradient.png diff --git a/docs/assets/images/readme.png b/docs/assets/images/readme-logo-purple.png similarity index 100% rename from docs/assets/images/readme.png rename to docs/assets/images/readme-logo-purple.png diff --git a/docs/assets/images/toc-quick-links.png b/docs/assets/images/table-of-contents/toc-quick-links.png similarity index 100% rename from docs/assets/images/toc-quick-links.png rename to docs/assets/images/table-of-contents/toc-quick-links.png diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index f3d5950b..00000000 --- a/docs/cli.md +++ /dev/null @@ -1,129 +0,0 @@ -# CLI Reference - -README-AI offers a wide range of configuration options to customize your README generation. This page provides a comprehensive list of all available options with detailed explanations. - -## CLI Options - -| Option | Description | Default | Impact | -|--------|-------------|---------|--------| -| `--align` | Text alignment in header | `center` | Affects the visual layout of the README header | -| `--api` | LLM API service | `offline` | Determines which AI service is used for content generation | -| `--badge-color` | Badge color (name or hex) | `0080ff` | Customizes the color of status badges in the README | -| `--badge-style` | Badge icon style type | `flat` | Changes the visual style of status badges | -| `--base-url` | Base URL for the repository | `v1/chat/completions` | Used for API requests to the chosen LLM service | -| `--context-window` | Max context window of LLM API | `3999` | Limits the amount of context provided to the LLM | -| `--emojis` | Add emojis to README sections | `False` | Adds visual flair to section headers | -| `--header-style` | Header template style | `classic` | Changes the overall look of the README header | -| `--image` | Project logo image | `blue` | Sets the main image displayed in the README | -| `--model` | Specific LLM model to use | `gpt-3.5-turbo` | Chooses the AI model for content generation | -| `--output` | Output filename | `readme-ai.md` | Specifies the name of the generated README file | -| `--rate-limit` | Max API requests per minute | `5` | Prevents exceeding API rate limits | -| `--repository` | Repository URL or local path | `None` | Specifies the project to analyze | -| `--temperature` | Creativity level for generation | `0.9` | Controls the randomness of the AI's output | -| `--toc-style` | Table of contents style | `bullet` | Changes the format of the table of contents | -| `--top-p` | Top-p sampling probability | `0.9` | Fine-tunes the AI's output diversity | -| `--tree-depth` | Max depth of directory tree | `2` | Controls the detail level of the project structure | - -## CLI Usage Examples - -### Using OpenAI - -```sh -readmeai --api openai --model gpt-3.5-turbo --repository https://github.com/username/project \ -``` - -### Using Ollama - -```sh -ollama run llama3 -``` - -```sh -readmeai --api ollama --model llama3 --repository https://github.com/username/project \ -``` - -### Generate README with Google Gemini - -```sh -readmeai --repository https://github.com/username/project \ - --api gemini \ - --model gemini-1.5-flash -``` - -### Generate README in Offline Mode - -```sh -readmeai --repository https://github.com/username/project \ - --api offline -``` - -### Customize Badge Style and Color - -```sh -readmeai --repository https://github.com/username/project \ - --api openai \ - --badge-style flat-square \ - --badge-color FF5733 -``` - -### Use Custom Project Logo - -```sh -readmeai --repository https://github.com/username/project \ - --api openai \ - --image custom -``` - -When prompted, enter the path or URL to your custom logo image. - -### Generate README with Emojis - -```sh -readmeai --repository https://github.com/username/project \ - --api openai \ - --emojis -``` - -These examples demonstrate basic usage of readme-ai. Lets take a look at some more advanced configurations and options next. - -## Advanced Configurations - -The following examples demonstrate advanced configurations and options for generating a README using readme-ai. - -### Generate README with Custom OpenAI API Parameters - -```sh -readmeai --repository /path/to/project \ - --api openai \ - --model gpt-4-turbo - --context-window 9999 - --temperature 0.1 - --rate-limit 20 -``` - -### Generate README with Specific Directory Depth - -```sh -readmeai --repository /path/to/project \ - --api openai \ - --tree-depth 3 -``` - -### Generate README with LLM API Parameters - -```sh -readmeai --repository /path/to/project \ - --api openai \ - --model gpt-4-turbo - --context-window 4999 - --temperature 0.7 - --top-p 0.8 -``` - -### Generate README with Custom Table of Contents Style - -```sh -readmeai --repository /path/to/project \ - --api openai \ - --toc-style fold -``` diff --git a/docs/customization/badges.md b/docs/configuration/badges.md similarity index 100% rename from docs/customization/badges.md rename to docs/configuration/badges.md diff --git a/docs/configuration/cli_reference.md b/docs/configuration/cli_reference.md new file mode 100644 index 00000000..073ff0c2 --- /dev/null +++ b/docs/configuration/cli_reference.md @@ -0,0 +1,29 @@ +--- +title: Configuration +--- + +README-AI offers a wide range of configuration options to customize your README generation. This page provides a comprehensive list of all available options with detailed explanations. + +## CLI Options + +| Option | Description | Default | Impact | +|--------|-------------|---------|--------| +| `--align` | Text alignment in header | `center` | Affects the visual layout of the README header | +| `--api` | LLM API service | `offline` | Determines which AI service is used for content generation | +| `--badge-color` | Badge color (name or hex) | `0080ff` | Customizes the color of status badges in the README | +| `--badge-style` | Badge icon style type | `flat` | Changes the visual style of status badges | +| `--base-url` | Base URL for the repository | `v1/chat/completions` | Used for API requests to the chosen LLM service | +| `--context-window` | Max context window of LLM API | `3999` | Limits the amount of context provided to the LLM | +| `--emojis` | Add emojis to README sections | `False` | Adds visual flair to section headers | +| `--header-style` | Header template style | `classic` | Changes the overall look of the README header | +| `--image` | Project logo image | `blue` | Sets the main image displayed in the README | +| `--model` | Specific LLM model to use | `gpt-3.5-turbo` | Chooses the AI model for content generation | +| `--output` | Output filename | `readme-ai.md` | Specifies the name of the generated README file | +| `--rate-limit` | Max API requests per minute | `5` | Prevents exceeding API rate limits | +| `--repository` | Repository URL or local path | `None` | Specifies the project to analyze | +| `--temperature` | Creativity level for generation | `0.9` | Controls the randomness of the AI's output | +| `--toc-style` | Table of contents style | `bullet` | Changes the format of the table of contents | +| `--top-p` | Top-p sampling probability | `0.9` | Fine-tunes the AI's output diversity | +| `--tree-depth` | Max depth of directory tree | `2` | Controls the detail level of the project structure | + +Some options have a significant impact on the generated README's appearance and content. Experiment with different settings to find the best configuration for your project. diff --git a/docs/customization/emojis.md b/docs/configuration/emojis.md similarity index 100% rename from docs/customization/emojis.md rename to docs/configuration/emojis.md diff --git a/docs/customization/header.md b/docs/configuration/header.md similarity index 100% rename from docs/customization/header.md rename to docs/configuration/header.md diff --git a/docs/customization/project_logo.md b/docs/configuration/project_logo.md similarity index 76% rename from docs/customization/project_logo.md rename to docs/configuration/project_logo.md index f50773a2..ae284a64 100644 --- a/docs/customization/project_logo.md +++ b/docs/configuration/project_logo.md @@ -80,10 +80,10 @@ Here's an example of how a generated README header might look with a logo: !!! example - === "Generated README Header with Logo" + === "Example 1"

- Project Logo + Project Logo

Your Project Name

@@ -91,15 +91,30 @@ Here's an example of how a generated README header might look with a logo:

-## LLM-Generated Logo Example + === "Example 2" -Here's an example of a logo generated using the OpenAI DALL-E model: +

+ Project Logo +

+

Your Project Name

+

+ Your project's tagline or brief description +

+ + === "Example 3" + +

+ Project Logo +

+

Your Project Name

+

+ Your project's tagline or brief description +

+ -
- ![LLM Generated Logo](https://github.com/eli64s/readme-ai/blob/main/docs/assets/images/dalle/readme-ai.png?raw=true){ width="300" } -
Logo generated using OpenAI's DALL-E model
-
+ +:warning: The quality and relevance of LLM-generated logos can vary. It's a good idea to review and potentially edit the generated logo to ensure it meets your project's needs. ## Tips for Using Project Logos @@ -109,6 +124,3 @@ Here's an example of a logo generated using the OpenAI DALL-E model: - When using LLM-generated logos, you may want to generate several options to choose from. - Consider how the logo will look alongside your project's badges and other README content. - If your project is part of a larger organization or ecosystem, consider using a logo that aligns with that branding. - -!!! info "Note on LLM-Generated Logos" -The quality and relevance of LLM-generated logos can vary. It's a good idea to review and potentially edit the generated logo to ensure it meets your project's needs. diff --git a/docs/customization/table_of_contents.md b/docs/configuration/table_of_contents.md similarity index 100% rename from docs/customization/table_of_contents.md rename to docs/configuration/table_of_contents.md diff --git a/docs/css/extra.css b/docs/css/extra.css index 136ac133..fe79b571 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -33,7 +33,7 @@ body { font-feature-settings: "kern", "liga", "clig", "calt"; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; - font-family: 'Roboto', sans-serif; + font-family: 'Arial', sans-serif; } .md-grid { diff --git a/docs/examples/use_cases.md b/docs/examples/use_cases.md index e69de29b..81b607fb 100644 --- a/docs/examples/use_cases.md +++ b/docs/examples/use_cases.md @@ -0,0 +1,104 @@ + diff --git a/docs/guides/markdown_best_practices.md b/docs/guides/markdown_best_practices.md index e7141691..ed5d9477 100644 --- a/docs/guides/markdown_best_practices.md +++ b/docs/guides/markdown_best_practices.md @@ -225,6 +225,12 @@ $$ ## Images +### [Simple Icons](https://simpleicons.org/) + +# Docker + +# Docker + ### Centered Images

diff --git a/docs/index.md b/docs/index.md index 3db37824..20905bdf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,11 +2,10 @@ title: README-AI --- -

-

README-AI

-

Your AI-Powered README Generator

-

Designed for simplicity, customization, and developer productivity.

+

README-AI

+

Your AI-Powered README Generator

+

Designed for simplicity, customization, and developer productivity.

github-actions @@ -26,34 +25,41 @@ title: README-AI
- +## Key Features -## Introduction +- :rocket: Automated README generation +- :art: Customizable output and styling +- :globe_with_meridians: Language and project agnostic +- :brain: Multi-LLM support +- :memo: Markdown best practices -**README-AI** is a developer tool and framework that combines the best of both worlds: robust data processing modules and generative AI models. It is designed to streamline the documentation process and enhance developer productivity by auto-generating comprehensive `README.md` files. +## Quick Start -With **README-AI**, you can: +If you're ready to jump right in, here's how to get started: -- **Automated Documentation**: Synchronize data from third-party sources and generates documentation automatically. +### Installation -- **Customization & Flexibility**: Dozens of options for styling/formatting, badges, header designs, and more. +```bash +pip install readmeai +``` -- **Language & Project Agnostic**: Works across a wide range of programming languages and project types. +### Usage -- **Multi-LLM Support**: Compatible with `OpenAI`, `Ollama`, `Anthropic`, `Google Gemini` and `Offline Mode`. +```bash +readmeai -r -o +``` -* **Markdown Best Practices**: Leverage best practices in Markdown formatting for clean, professional-looking documentation. +Otherwise you can explore the [documentation](quickstart/prerequisites.md) for more detailed information. Cheers! -For usage instructions, see the [Usage](../usage/cli.md) documentation. +For usage instructions, see the [Usage](../usage/cli.md) section. diff --git a/docs/help.md b/docs/troubleshooting.md similarity index 96% rename from docs/help.md rename to docs/troubleshooting.md index 153486ce..e76905d5 100644 --- a/docs/help.md +++ b/docs/troubleshooting.md @@ -1,4 +1,6 @@ -# Getting Help +--- +title: Troubleshooting +--- ## Help Menus diff --git a/docs/usage/docker.md b/docs/usage/docker.md index ef18af6a..378fb303 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -3,7 +3,16 @@ hide: - title --- -# Docker  docker-pulls docker-size

+# Docker + + Running readme-ai in a containerized environment using Docker offers isolation of the application and its dependencies from the host system. This section details how to pull the Docker image from Docker Hub, build the Docker image from the source code, and run the Docker container. @@ -35,10 +44,10 @@ Run the readme-ai Docker container with the following command: ```sh docker run -it --rm \ - -e OPENAI_API_KEY=$OPENAI_API_KEY \ - -v "$(pwd)":/app \ - zeroxeli/readme-ai:latest \ - -r https://github.com/eli64s/readme-ai +-e OPENAI_API_KEY=$OPENAI_API_KEY \ +-v "$(pwd)":/app zeroxeli/readme-ai:latest \ +-r https://github.com/eli64s/readme-ai \ +--api openai ``` Explanation of the command arguments: diff --git a/docs/usage/pip.md b/docs/usage/pip.md index eaec4ad9..ce1ab0eb 100644 --- a/docs/usage/pip.md +++ b/docs/usage/pip.md @@ -1,56 +1,16 @@ --- -title: Pip +hide: + - title --- -# Using `pip`

pypi-version  github-stars

- -## Installation - -To install `readmeai` from PyPI, simply run: - -```sh -pip install readmeai -``` - -`pip` is the default Python package manager, and this command will download and install the latest version of `readmeai` from the Python Package Index (PyPI). - -## With `pipx` - -To install `readmeai` in an isolated environment using `pipx`, run: - -```sh -pipx install readmeai -``` -#### Using `pip` - -[![pip](https://img.shields.io/badge/PyPI-3775A9.svg?style=flat&logo=PyPI&logoColor=white)](https://pypi.org/project/readmeai/) - -???+ note "Python Version Requirement" - Ensure you have Python version 3.9 or higher before installing readme-ai. For the latest Python installation guide, visit the - -## Installation Using Pip - -To install readme-ai from PyPI, simply run: - -```sh -pipx install readmeai -``` - -`pip` is the default Python package manager, and this command will download and install the latest version of readme-ai from the Python Package Index (PyPI). - -## Using `pip` - -To install readme-ai in an isolated environment using `pipx`, run: - -```sh -pipx install readmeai -``` - -???+ info "Why Use Pipx?" - `pipx` allows you to install and run Python command-line applications in isolated environments, preventing conflicts with other Python projects. - - -## Running readme-ai + After installation, you can run readme-ai with: @@ -58,57 +18,6 @@ After installation, you can run readme-ai with: readmeai --api openai --repository https://github.com/eli64s/readme-ai ``` -Explanation of common arguments: - -| Argument | Description | -| ----------- | ------------------------------------ | -| `--api` | Specifies the LLM API service to use (e.g., OpenAI, Ollama, Anthropic). | -| `--repository` | Specifies the GitHub repository or local directory path to analyze. | - -## Building from Source - -To build readme-ai from the source code, follow these steps: - -1. Clone the repository from GitHub: - -```sh -git clone https://github.com/eli64s/readme-ai -``` - -2. Navigate to the `readme-ai` directory: - -```sh -cd readme-ai -``` - -3. Install dependencies: - -```sh -pip install . -``` - -Alternatively, use `poetry` to build the project: - -```sh -poetry install -``` - -## Optional Dependencies - -To use additional LLM providers like **Anthropic** or **Google Gemini**, install the optional dependencies: - -**Anthropic**: - -```sh -pip install readmeai[anthropic] -``` - -**Google Gemini**: - -```sh -pip install readmeai[gemini] -``` - ## Usage ### Setting Environment Variables @@ -162,149 +71,3 @@ readmeai --help 3. **Missing Dependencies**: Some advanced features require additional Python packages. Check the [official documentation](https://github.com/eli64s/readme-ai) for a list of optional dependencies. For further help, you can [open an issue](https://github.com/eli64s/readme-ai/issues) on GitHub or refer to the [official documentation](https://eli64s.github.io/readme-ai/). - -## With Pip

- -pypi-version - - github-stars

- -Installing readme-ai using `pip` or `pipx` makes it easy to get started with the tool, allowing you to directly use the CLI in your local environment. This section details how to install readme-ai using `pip`, `pipx`, and additional methods like building from source or using Docker. - -???+ note "Python Version Requirement" - Ensure you have Python version 3.9 or higher before installing readme-ai. For the latest Python installation guide, visit the [official Python documentation](https://www.python.org/downloads/). - -## Installation with Pip - -Install readme-ai from PyPI with a single command: - -```sh -pip install readmeai -``` - -Pip is the standard package manager for Python, and this command will download and install the latest version of readme-ai from the Python Package Index (PyPI). - -## Installation with Pipx - -Install readme-ai in an isolated environment using `pipx` to avoid conflicts between package dependencies: - -```sh -pipx install readmeai -``` - -???+ info "Why Pipx?" - Using `pipx` allows you to install and run Python command-line applications in isolated environments, which helps prevent dependency conflicts with other Python projects. - -## Running the CLI - -Run readme-ai directly after installation: - -```sh -readmeai --api openai --repository https://github.com/eli64s/readme-ai -``` - -Explanation of common arguments: - -| Argument | Function | -| ----------- | ------------------------------------ | -| `--api` | Specifies the LLM API service to use (e.g., OpenAI, Ollama, Anthropic). | -| `--repository` | Specifies the GitHub repository or local directory path to analyze. | - - -## Building from Source - -To build readme-ai from the source code, follow these steps: - -1. Clone the repository from GitHub: - -```sh -git clone https://github.com/eli64s/readme-ai -``` - -2. Navigate to the `readme-ai` directory: - -```sh -cd readme-ai -``` - -3. Install dependencies: - -```sh -pip install . -``` - -Alternatively, you can use `poetry` to build the project: - -```sh -poetry install -``` - -## Optional Dependencies - -To use additional LLM providers like **Anthropic** or **Google Gemini**, install the optional dependencies: - -Anthropic: - -```sh -pip install readmeai[anthropic] -``` - -Google Gemini: - -```sh -pip install readmeai[gemini] -``` - -## Usage - -### Setting Environment Variables - -**OpenAI API Key** - -Ensure you have generated an OpenAI API key and set it as an environment variable: - -```sh -export OPENAI_API_KEY= -``` - -For Windows users, use: - -```sh -set OPENAI_API_KEY= -``` - -**Anthropic API Key** - -To use the Anthropic API, set your Anthropic API key: - -```sh -export ANTHROPIC_API_KEY= -``` - -### Example Usage - -Run readme-ai with OpenAI: - -```sh -readmeai --api openai --repository https://github.com/eli64s/readme-ai -``` - -Run readme-ai with Anthropic: - -```sh -readmeai --api anthropic --repository https://github.com/eli64s/readme-ai -``` - -For a list of all available options, run: - -```sh -readmeai --help -``` - -## Troubleshooting - -1. **Permission Issues**: Ensure you have the necessary permissions to install Python packages. You may need to use `sudo` on Unix-based systems. -2. **Pipx Not Found**: Make sure pipx is properly installed and available in your PATH. You can find installation instructions [here](https://pipxproject.github.io/pipx/installation/). -3. **Missing Dependencies**: Some advanced features require additional Python packages. Check the [official documentation](https://github.com/eli64s/readme-ai) for a list of optional dependencies. - -For further help, you can [open an issue](https://github.com/eli64s/readme-ai/issues) on GitHub or refer to the [official documentation](https://eli64s.github.io/readme-ai/). diff --git a/docs/usage/streamlit.md b/docs/usage/streamlit.md index 8f96dec4..0a86da7f 100644 --- a/docs/usage/streamlit.md +++ b/docs/usage/streamlit.md @@ -1,5 +1,8 @@ -# Try it on Streamlit +# Streamlit Run readme-ai directly in your browser on Streamlit Cloud. No installation required! Open In Streamlit + +!!! tip "Source Code" + Find the source code for the Streamlit app in the [readme-ai repository](https;//github.com/eli64s/readme-ai-streamlit.) diff --git a/examples/readme-chunking.md b/examples/readme-chunking.md new file mode 100644 index 00000000..7e12c1b1 --- /dev/null +++ b/examples/readme-chunking.md @@ -0,0 +1,282 @@ +

+ +

+

THEPIPE

+

Unleash Efficiency, Embrace Innovation!

+

+ license + last-commit + repo-top-language + repo-language-count +

+

Built with the tools and technologies:

+

+ scikitlearn + Supabase + Python + GitHub%20Actions + AIOHTTP + Pydantic +

+
+ +## Table of Contents + +- [ Overview](#-overview) +- [ Features](#-features) +- [ Project Structure](#-project-structure) + - [ Project Index](#-project-index) +- [ Getting Started](#-getting-started) + - [ Prerequisites](#-prerequisites) + - [ Installation](#-installation) + - [ Usage](#-usage) + - [ Testing](#-testing) +- [ Project Roadmap](#-project-roadmap) +- [ Contributing](#-contributing) +- [ License](#-license) +- [ Acknowledgments](#-acknowledgments) + +--- + +## Overview + +**thepipe** is an open-source project designed to streamline data extraction, processing, and management tasks within AI-native applications. It simplifies web scraping, document processing, and multimedia manipulation, catering to developers working on AI-powered solutions. + +With **thepipe**, you can: +๐Ÿš€ **Efficient Web Scraping**: Seamlessly extract data from various sources using concurrent processing and chunking algorithms. +๐Ÿ”ง **Document Processing**: Organize and group text chunks for enhanced readability and analysis in document processing tasks. +๐ŸŒ **AI Text Extraction**: Utilize AI models for data extraction from URLs and files, providing structured JSON output. +๐Ÿ”’ **Compression Capabilities**: Compress project files into context prompts for efficient management and processing. +โšก **Automation**: Automate Python package publishing, testing, and code coverage for streamlined development workflows. + +--- + +## Features + +| | Feature | Summary | +| :--- | :---: | :--- | +| โš™๏ธ | **Architecture** |
  • Utilizes **`aiohttp`** for asynchronous HTTP requests handling.
  • Employs **concurrent processing** and **chunking algorithms** for efficient data extraction and organization.
  • Interacts with **external APIs** and services to enhance project functionality.
| +| ๐Ÿ”ฉ | **Code Quality** |
  • Maintains a stable and efficient codebase architecture through **seamless integration** of essential libraries like **`llama-index`**, **`scikit-learn`**, and others.
  • Defines project dependencies and configurations using **`setup.py`** for clear management.
  • Utilizes **`flake8`** linting and **unittest** for code quality assurance.
| +| ๐Ÿ“„ | **Documentation** |
  • Facilitates project dependencies management through the **`requirements.txt`** file.
  • Provides clear installation and usage commands for the project.
  • Automates Python package publishing and testing with **`.github/workflows/python-publish.yml`** and **`.github/workflows/python-ci.yml`** respectively.
| +| ๐Ÿ”Œ | **Integrations** |
  • Integrates with **external APIs** for enhanced functionality.
  • Automates Python package publishing on GitHub releases using **`.github/workflows/python-publish.yml`**.
  • Automates Python testing and code coverage with **Playwright setup** and **Codecov report upload** in **`.github/workflows/python-ci.yml`**.
| +| ๐Ÿงฉ | **Modularity** |
  • Facilitates seamless integration of essential libraries for document processing and multimedia manipulation within the project architecture through **`local.txt`**.
  • Organizes text chunks efficiently for readability and analysis using **`thepipe/chunker.py`**.
  • Supports various extraction configurations and data processing capabilities through **`thepipe/extract.py`**.
| +| ๐Ÿงช | **Testing** |
  • Ensures code quality through **`pytest`** testing.
  • Automates Python testing and code coverage with **Playwright setup** and **Codecov report upload** in **`.github/workflows/python-ci.yml`**.
  • Integrates **unittest** for comprehensive testing coverage.
| +| โšก๏ธ | **Performance** |
  • Utilizes **asynchronous HTTP requests handling** with **`aiohttp`** for improved performance.
  • Employs **concurrent processing** and **chunking algorithms** for efficient data extraction.
  • Supports **local execution** for efficient project management.
| + +--- + +## Project Structure + +```sh +โ””โ”€โ”€ thepipe/ + โ”œโ”€โ”€ .github + โ”‚ โ””โ”€โ”€ workflows + โ”œโ”€โ”€ LICENSE + โ”œโ”€โ”€ README.md + โ”œโ”€โ”€ local.txt + โ”œโ”€โ”€ requirements.txt + โ”œโ”€โ”€ setup.py + โ”œโ”€โ”€ tests + โ”‚ โ”œโ”€โ”€ __init__.py + โ”‚ โ”œโ”€โ”€ files + โ”‚ โ”œโ”€โ”€ test_api.py + โ”‚ โ”œโ”€โ”€ test_chunker.py + โ”‚ โ”œโ”€โ”€ test_core.py + โ”‚ โ”œโ”€โ”€ test_extractor.py + โ”‚ โ””โ”€โ”€ test_scraper.py + โ””โ”€โ”€ thepipe + โ”œโ”€โ”€ __init__.py + โ”œโ”€โ”€ chunker.py + โ”œโ”€โ”€ core.py + โ”œโ”€โ”€ extract.py + โ””โ”€โ”€ scraper.py +``` + + +### Project Index +
+ THEPIPE/ +
+ __root__ +
+ + + + + + + + + + + + + +
requirements.txt- Facilitates project dependencies management by specifying required packages and versions in the 'requirements.txt' file
- This ensures seamless integration of essential libraries like 'llama-index', 'aiohttp', 'scikit-learn', and others, maintaining a stable and efficient codebase architecture.
setup.py- Define project dependencies and configurations using setup.py for 'thepipe_api', an AI-native extractor powered by multimodal LLMs
- Include author details, description, version, and entry points for console scripts
- Utilize requirements.txt and local.txt for install and extra dependencies, respectively.
local.txtFacilitates seamless integration of essential libraries for document processing and multimedia manipulation within the project architecture.
+
+
+
+ thepipe +
+ + + + + + + + + + + + + + + + + +
scraper.py- The `scraper.py` file in the `thepipe` directory is responsible for handling web scraping tasks, extracting data from various sources, and processing it for further analysis within the codebase architecture
- It utilizes concurrent processing, image manipulation, and chunking algorithms to efficiently gather and organize information
- Additionally, it interacts with external APIs and services to enhance the functionality of the project.
chunker.py- Chunking functions in the code file segment text data into meaningful sections based on document structure, pages, sections, semantics, or keywords
- These functions organize and group text chunks to enhance readability and analysis, supporting various document processing tasks within the codebase architecture.
core.py- Enables compression of project files into a context prompt by processing text and images, generating tokens, and saving outputs
- Parses arguments for source files, regex patterns, AI text extraction, and verbosity
- Supports local execution and facilitates efficient project management.
extract.py- The code file `extract.py` facilitates data extraction from URLs and files using AI models, providing structured JSON output
- It handles multiple extraction scenarios, error handling, and token calculation
- The file integrates with external APIs and supports various extraction configurations, contributing to the project's data processing capabilities.
+
+
+
+ .github +
+
+ workflows +
+ + + + + + + + + +
python-publish.ymlAutomates Python package publishing on GitHub releases by building and uploading the package to PyPI.
python-ci.yml- Automates Python testing and code coverage with Playwright setup, Tesseract OCR installation, and Codecov report upload
- Integrates flake8 linting, unittest, and coverage generation for the project.
+
+
+
+
+
+ +--- +## Getting Started + +### Prerequisites + +Before getting started with thepipe, ensure your runtime environment meets the following requirements: + +- **Programming Language:** Python +- **Package Manager:** Pip + + +### Installation + +Install thepipe using one of the following methods: + +**Build from source:** + +1. Clone the thepipe repository: +```sh +โฏ git clone https://github.com/emcf/thepipe +``` + +2. Navigate to the project directory: +```sh +โฏ cd thepipe +``` + +3. Install the project dependencies: + + +**Using `pip`**   [](https://pypi.org/project/pip/) + +```sh +โฏ pip install -r requirements.txt +``` + + + + +### Usage +Run thepipe using the following command: +**Using `pip`**   [](https://pypi.org/project/pip/) + +```sh +โฏ python {entrypoint} +``` + + +### Testing +Run the test suite using the following command: +**Using `pip`**   [](https://pypi.org/project/pip/) + +```sh +โฏ pytest +``` + + +--- +## Project Roadmap + +- [X] **`Task 1`**: Implement feature one. +- [ ] **`Task 2`**: Implement feature two. +- [ ] **`Task 3`**: Implement feature three. + +--- + +## Contributing + +- **๐Ÿ’ฌ [Join the Discussions](https://github.com/emcf/thepipe/discussions)**: Share your insights, provide feedback, or ask questions. +- **๐Ÿ› [Report Issues](https://github.com/emcf/thepipe/issues)**: Submit bugs found or log feature requests for the `thepipe` project. +- **๐Ÿ’ก [Submit Pull Requests](https://github.com/emcf/thepipe/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs. + +
+Contributing Guidelines + +1. **Fork the Repository**: Start by forking the project repository to your github account. +2. **Clone Locally**: Clone the forked repository to your local machine using a git client. + ```sh + git clone https://github.com/emcf/thepipe + ``` +3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name. + ```sh + git checkout -b new-feature-x + ``` +4. **Make Your Changes**: Develop and test your changes locally. +5. **Commit Your Changes**: Commit with a clear message describing your updates. + ```sh + git commit -m 'Implemented new feature x.' + ``` +6. **Push to github**: Push the changes to your forked repository. + ```sh + git push origin new-feature-x + ``` +7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations. +8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution! +
+ +
+Contributor Graph +
+

+ + + +

+
+ +--- + +## License + +This project is protected under the [SELECT-A-LICENSE](https://choosealicense.com/licenses) License. For more details, refer to the [LICENSE](https://choosealicense.com/licenses/) file. + +--- + +## Acknowledgments + +- List any resources, contributors, inspiration, etc. here. + +--- diff --git a/examples/readme-vercel.md b/examples/readme-vercel.md new file mode 100644 index 00000000..582a423e --- /dev/null +++ b/examples/readme-vercel.md @@ -0,0 +1,317 @@ +

+ +

+

GITHUB-README-QUOTES

+

Code consistency, creativity, and motivation unleashed!

+

+ license + last-commit + repo-top-language + repo-language-count +

+

Built with the tools and technologies:

+

+ Vercel + npm + Prettier + TypeScript + Axios +

+
+ +## ๐Ÿ”— Table of Contents + +I. [๐Ÿ“ Overview](#-overview) +II. [๐Ÿ‘พ Features](#-features) +III. [๐Ÿ“ Project Structure](#-project-structure) +IV. [๐Ÿš€ Getting Started](#-getting-started) +V. [๐Ÿ“Œ Project Roadmap](#-project-roadmap) +VI. [๐Ÿ”ฐ Contributing](#-contributing) +VII. [๐ŸŽ— License](#-license) +VIII. [๐Ÿ™Œ Acknowledgments](#-acknowledgments) + +--- + +## ๐Ÿ“ Overview + +**github-readme-quotes** is a project aimed at enhancing GitHub README profiles by dynamically displaying inspirational programming quotes in the form of customizable SVG images. It allows developers to add a touch of motivation and personalization to their repositories, creating a more engaging and interactive experience for visitors. + +With **github-readme-quotes**, you can: +๐ŸŽจ **Customizable Themes**: Personalize the appearance of the quote cards with different themes and color schemes. +๐Ÿ”„ **Dynamic Quote Generation**: Fetch random programming quotes to display fresh and motivational content. +๐Ÿ“ **SVG Card Customization**: Customize the layout, font, and border of the SVG cards to match your README style. +๐Ÿš€ **Caching Support**: Implement caching mechanisms to improve performance and reduce external API calls. +๐ŸŒ **Vercel Integration**: Easily deploy and serve the generated SVG images using Vercel's serverless functions. + +--- + +## ๐Ÿ‘พ Features + +| | Feature | Summary | +| :--- | :---: | :--- | +| โš™๏ธ | **Architecture** |
  • Utilizes **TypeScript** for type safety and enhanced developer experience.
  • Implements **Vercel** for serverless functions and routing management.
  • Uses **Axios** for making HTTP requests to external APIs.
| +| ๐Ÿ”ฉ | **Code Quality** |
  • Includes a **Prettier** script in `package.json` for consistent code formatting.
  • Employs strict type-checking settings in `tsconfig.json` for improved code quality.
  • Utilizes a lockfile `pnpm-lock.yaml` to manage dependency versions and ensure reproducibility.
| +| ๐Ÿ“„ | **Documentation** |
  • Primary language is **TypeScript**.
  • Contains documentation in various formats such as **JSON**, **YAML**, and **TypeScript**.
  • Defines installation and usage commands in the documentation for easy onboarding.
| +| ๐Ÿ”Œ | **Integrations** |
  • Integrates with **Vercel** for hosting and serverless functions.
  • Utilizes **Axios** for fetching external API data.
  • Integrates with **npm** for package management.
| +| ๐Ÿงฉ | **Modularity** |
  • Separates components like fetcher, renderer, and themes into distinct modules for maintainability.
  • Defines specific card types like horizontal and vertical for modularity and extensibility.
  • Encapsulates font data and theme configurations within separate files for easy management.
| +| ๐Ÿงช | **Testing** |
  • Includes testing commands in the documentation for running unit tests.
  • Ensures testability of components like fetcher and renderer for code reliability.
  • Tests the API functionality for fetching and rendering quotes dynamically.
| +| โšก๏ธ | **Performance** |
  • Supports caching of image responses to improve performance.
  • Optimizes SVG rendering for fast generation of quote cards.
  • Utilizes serverless functions for efficient quote generation and delivery.
| +| ๐Ÿ›ก๏ธ | **Security** |
  • Follows security best practices for making external API requests.
  • Secures API endpoints to prevent unauthorized access.
  • Implements secure coding practices to prevent common vulnerabilities.
| +| ๐Ÿ“ฆ | **Dependencies** |
  • Lists key dependencies like **Axios**, **Vercel**, and **TypeScript** in `package.json`.
  • Specifies versions and dependencies accurately in the lockfile `pnpm-lock.yaml`.
  • Manages package installation using **npm** as the package manager.
| + +--- + +## ๐Ÿ“ Project Structure + +```sh +โ””โ”€โ”€ github-readme-quotes/ + โ”œโ”€โ”€ .github + โ”‚ โ””โ”€โ”€ FUNDING.yml + โ”œโ”€โ”€ LICENSE + โ”œโ”€โ”€ README.md + โ”œโ”€โ”€ api + โ”‚ โ””โ”€โ”€ index.ts + โ”œโ”€โ”€ assets + โ”‚ โ””โ”€โ”€ logo.png + โ”œโ”€โ”€ package.json + โ”œโ”€โ”€ pnpm-lock.yaml + โ”œโ”€โ”€ src + โ”‚ โ”œโ”€โ”€ fetcher + โ”‚ โ”‚ โ””โ”€โ”€ fetch-quotes.ts + โ”‚ โ””โ”€โ”€ renderer + โ”‚ โ”œโ”€โ”€ constants.ts + โ”‚ โ”œโ”€โ”€ render-svg.ts + โ”‚ โ”œโ”€โ”€ theme + โ”‚ โ””โ”€โ”€ type + โ”œโ”€โ”€ tsconfig.json + โ””โ”€โ”€ vercel.json +``` + + +### ๐Ÿ“‚ Project Index +
+ GITHUB-README-QUOTES/ +
+ __root__ +
+ + + + + + + + + + + + + + + + + +
pnpm-lock.yaml- The code file `pnpm-lock.yaml` serves as a lockfile for managing dependencies within the project architecture
- It specifies the versions of various dependencies such as '@vercel/node', axios, prettier, typescript, and vercel, ensuring consistency and reproducibility in the project's environment
- This file plays a crucial role in maintaining a stable and predictable development environment by pinning down specific versions of dependencies required for the project.
vercel.json- Defines memory allocation and maximum duration for API functions, and sets up a redirect to the project's GitHub page
- This configuration file plays a crucial role in managing serverless functions and routing within the project structure.
package.json- Implements a script that formats code using Prettier across TypeScript, JSON, and Markdown files in the project
- The script ensures consistent code styling and readability, enhancing the overall maintainability and collaboration within the codebase.
tsconfig.jsonEnables strict type-checking and interoperability settings across the project, ensuring consistent code quality and compatibility.
+
+
+
+ .github +
+ + + + + +
FUNDING.ymlFacilitates financial support for the project by defining supported funding platforms.
+
+
+
+ api +
+ + + + + +
index.ts- Generates SVG images with quotes based on query parameters, utilizing fetcher and renderer functions
- Allows customization of card type, theme, quote content, author, and border
- Supports caching and delivers image responses via Vercel.
+
+
+
+ src +
+
+ renderer +
+ + + + + + + + + +
render-svg.ts- Defines a function to render SVG cards based on input data, type, theme, and border settings
- Renders vertical or horizontal cards with specified colors and themes, falling back to defaults when necessary
- This function enhances the project's renderer capabilities, supporting various card types and themes for visual representation.
constants.ts- Define and export a constant storing SVG font data for the "Poppins" font family in the renderer component
- This file manages the configuration for displaying text in the specified font style and weight.
+
+ type +
+ + + + + + + + + +
horizontal-card.ts- Generates a horizontal card displaying a quote with author, customizable themes, and borders based on user-defined props
- Handles light and dark mode themes, adapting to system settings or custom color schemes.
vertical-card.tsGenerate vertical card SVG markup based on quote, author, color, and border props using Poppins font and customizable themes.
+
+
+
+ theme +
+ + + + + +
awesome-card.ts- Define and export interface, themes, and render function for theme customization in the renderer layer
- Theme data includes quote, author, background, and symbol properties
- The renderTheme function validates and returns a specified theme or default light theme with dark mode support if not found.
+
+
+
+
+
+ fetcher +
+ + + + + +
fetch-quotes.ts- Enable fetching and parsing of random programming quotes from an external API
- Retrieves quotes data, selects a random quote, and parses it before returning the formatted quote along with its author
- This functionality aids in injecting dynamic and motivational content into the application to inspire users.
+
+
+
+
+
+ +--- +## ๐Ÿš€ Getting Started + +### โ˜‘๏ธ Prerequisites + +Before getting started with github-readme-quotes, ensure your runtime environment meets the following requirements: + +- **Programming Language:** TypeScript +- **Package Manager:** Npm + + +### โš™๏ธ Installation + +Install github-readme-quotes using one of the following methods: + +**Build from source:** + +1. Clone the github-readme-quotes repository: +```sh +โฏ git clone https://github.com/PiyushSuthar/github-readme-quotes +``` + +2. Navigate to the project directory: +```sh +โฏ cd github-readme-quotes +``` + +3. Install the project dependencies: + + +**Using `npm`**   [](https://www.npmjs.com/) + +```sh +โฏ npm install +``` + + + + +### ๐Ÿค– Usage +Run github-readme-quotes using the following command: +**Using `npm`**   [](https://www.npmjs.com/) + +```sh +โฏ npm start +``` + + +### ๐Ÿงช Testing +Run the test suite using the following command: +**Using `npm`**   [](https://www.npmjs.com/) + +```sh +โฏ npm test +``` + + +--- +## ๐Ÿ“Œ Project Roadmap + +- [X] **`Task 1`**: Implement feature one. +- [ ] **`Task 2`**: Implement feature two. +- [ ] **`Task 3`**: Implement feature three. + +--- + +## ๐Ÿ”ฐ Contributing + +- **๐Ÿ’ฌ [Join the Discussions](https://github.com/PiyushSuthar/github-readme-quotes/discussions)**: Share your insights, provide feedback, or ask questions. +- **๐Ÿ› [Report Issues](https://github.com/PiyushSuthar/github-readme-quotes/issues)**: Submit bugs found or log feature requests for the `github-readme-quotes` project. +- **๐Ÿ’ก [Submit Pull Requests](https://github.com/PiyushSuthar/github-readme-quotes/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs. + +
+Contributing Guidelines + +1. **Fork the Repository**: Start by forking the project repository to your github account. +2. **Clone Locally**: Clone the forked repository to your local machine using a git client. + ```sh + git clone https://github.com/PiyushSuthar/github-readme-quotes + ``` +3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name. + ```sh + git checkout -b new-feature-x + ``` +4. **Make Your Changes**: Develop and test your changes locally. +5. **Commit Your Changes**: Commit with a clear message describing your updates. + ```sh + git commit -m 'Implemented new feature x.' + ``` +6. **Push to github**: Push the changes to your forked repository. + ```sh + git push origin new-feature-x + ``` +7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations. +8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution! +
+ +
+Contributor Graph +
+

+ + + +

+
+ +--- + +## ๐ŸŽ— License + +This project is protected under the [SELECT-A-LICENSE](https://choosealicense.com/licenses) License. For more details, refer to the [LICENSE](https://choosealicense.com/licenses/) file. + +--- + +## ๐Ÿ™Œ Acknowledgments + +- List any resources, contributors, inspiration, etc. here. + +--- diff --git a/mkdocs.yml b/mkdocs.yml index bc684a28..cfa8805c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,14 +51,12 @@ theme: - navigation.prune - navigation.sections - navigation.tabs - # - navigation.tabs.sticky - navigation.top - navigation.tracking - search.highlight - search.share - search.suggest - toc.follow - # - toc.integrate palette: - scheme: default primary: black @@ -76,26 +74,6 @@ theme: text: Roboto code: Roboto Mono -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/eli64s/readme-ai - - icon: fontawesome/brands/python - link: https://pypi.org/project/readmeai/ - - icon: fontawesome/brands/docker - link: https://hub.docker.com/r/zeroxeli/readme-ai - analytics: - provider: google - property: G-XXXXXXXXXX - consent: - title: Cookie consent - description: >- - We use cookies to recognize your repeated visits and preferences, as well - as to measure the effectiveness of our documentation and whether users - find what they're searching for. With your consent, you're helping us to - make our documentation better. - category_to_de: docs/.overrides - markdown_extensions: - admonition - attr_list @@ -110,6 +88,9 @@ markdown_extensions: smart_enable: all - pymdownx.caret - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: anchor_linenums: true line_spans: __span @@ -141,6 +122,15 @@ plugins: - minify: minify_html: true +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/eli64s/readme-ai + - icon: fontawesome/brands/python + link: https://pypi.org/project/readmeai/ + - icon: fontawesome/brands/docker + link: https://hub.docker.com/r/zeroxeli/readme-ai + extra_css: - css/extra.css @@ -148,35 +138,28 @@ extra_javascript: - js/extra.js nav: - - Home: + - HOME: - index.md - - Why readme-ai?: why.md + - Why README-AI?: why.md # - Philosophy: philosophy.md - - Quickstart: quickstart/prerequisites.md - - Getting Help: help.md + - Quick Start: quickstart/prerequisites.md + - Troubleshooting: troubleshooting.md - Contributing: contributing.md - - - Getting Started: + - SETUP: - Prerequisites: quickstart/prerequisites.md - Installation: quickstart/installation.md - - Configuration: - cli.md - # - Overview: getting-started/configuration.md - # - Settings: configuration/settings.md - # - Templates: configuration/templates.md - # - Variables: configuration/variables.md - # - Plugins: configuration/plugins.md - - User Guide: - - CLI Usage: usage/cli.md + - USAGE: + - CLI: usage/cli.md - Docker: usage/docker.md - - Streamlit App: usage/streamlit.md - - Customizations: - - Badges: customization/badges.md - - Headers: customization/header.md - - Table of Contents: customization/table_of_contents.md - - Project Logo: customization/project_logo.md - - Emojis: customization/emojis.md - - Integrations: + - Streamlit: usage/streamlit.md + - CONFIGURATION: + - configuration/cli_reference.md + - Badges: configuration/badges.md + - Headers: configuration/header.md + - Table of Contents: configuration/table_of_contents.md + - Project Logo: configuration/project_logo.md + - Emojis: configuration/emojis.md + - INTEGRATIONS: - Models: - llms/index.md - OpenAI: llms/openai.md @@ -184,11 +167,10 @@ nav: - Anthropic: llms/anthropic.md - Google Gemini: llms/google_gemini.md - Offline Mode: llms/offline_mode.md + - EXAMPLES: + - Gallery: examples/gallery.md + # - Use Cases: examples/use-cases.md # - Advanced Topics: # - Best Practices: advanced/best-practices.md # - Custom Templates: advanced/custom-templates.md # - Markdown Guide: advanced/markdown-guide.md - - Examples: - - Gallery: examples/gallery.md - - Use Cases: examples/use-cases.md - - CLI Reference: cli.md