diff --git a/docs/docs/assets/svg/readme-ai-gradient.svg b/docs/docs/assets/svg/readme-ai-gradient.svg index fb2e8ece..d3190821 100644 --- a/docs/docs/assets/svg/readme-ai-gradient.svg +++ b/docs/docs/assets/svg/readme-ai-gradient.svg @@ -6,9 +6,9 @@ - + M - + README-AI diff --git a/docs/docs/cli.md b/docs/docs/cli-reference.md similarity index 81% rename from docs/docs/cli.md rename to docs/docs/cli-reference.md index 29dad479..d2dcb7f9 100644 --- a/docs/docs/cli.md +++ b/docs/docs/cli-reference.md @@ -1,5 +1,5 @@ --- -title: CLI Reference +title: "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. @@ -12,11 +12,11 @@ README-AI offers a wide range of configuration options to customize your README | `--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 | +| `--emojis` | Select emoji theme style | `default` | 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 | +| `--image-width` | Width of the project logo | `20%` | Sets the size of the project logo | | `--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 | @@ -26,6 +26,7 @@ README-AI offers a wide range of configuration options to customize your README | `--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! +!!! note "Note" + 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/docs/components/emoji_themes.md b/docs/docs/components/emoji_themes.md new file mode 100644 index 00000000..8c957c34 --- /dev/null +++ b/docs/docs/components/emoji_themes.md @@ -0,0 +1,349 @@ +--- +title: Emoji Theme Packs +--- + +# Emoji Theme Packs + +Emoji theme packs allow you to add domain-specific emoji prefixes to your README section headers. This can be a nice touch for enhancing visual navigation and project context. Each theme provides a carefully curated set of emojis aligned with different technology domains and project types. + +## Overview + +Use the `--emojis` flag along with your chosen theme to add emoji prefixes: + +```sh +readmeai --emojis --repository +``` + +## Available Themes + +### Core Themes + +=== ":octicons-mark-github-16: Default" + + Default theme *does not* include emojis. This is the default behavior when the `--emojis` flag is not set. + + ```sh + readmeai --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ### 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) + - [Roadmap](#roadmap) + - [Contributing](#contributing) + - [License](#license) + - [Acknowledgments](#acknowledgments) + +=== ":octicons-file-16: Minimal" + + Clean and simple emoji set. + + ```sh + readmeai --emojis minimal --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ```markdown + ## ๐Ÿ“„ Table of Contents + ## โœจ Overview + ## ๐Ÿ“Œ Features + ## ๐Ÿ“ Project Structure + ### ๐Ÿ“‘ Project Index + ## ๐Ÿš€ Getting Started + ### ๐Ÿ“‹ Prerequisites + ### โš™๏ธ Installation + ### ๐Ÿ’ป Usage + ### ๐Ÿงช Testing + ## ๐Ÿ“ˆ Roadmap + ## ๐Ÿค Contributing + ## ๐Ÿ“œ License + ## โœจ Acknowledgments + ``` + +=== ":octicons-code-16: OSS" + + Open source and community focused emojis. + + ```sh + readmeai --emojis oss --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ```markdown + ## ๐ŸŒŸ Table of Contents + ## ๐Ÿ’ซ Overview + ## โœจ Features + ## ๐Ÿ“ Project Structure + ### ๐Ÿ“‘ Project Index + ## ๐Ÿš€ Getting Started + ### ๐Ÿ“‹ Prerequisites + ### โš™๏ธ Installation + ### ๐Ÿ’ป Usage + ### ๐Ÿงช Testing + ## ๐Ÿ‘ฅ Community + ### ๐Ÿค Contributing + ### ๐Ÿ’ญ Code of Conduct + ### ๐Ÿ—ฃ๏ธ Discussions + ### ๐ŸŽฏ Issues + ## ๐Ÿ“š Documentation + ### ๐Ÿ“– API Reference + ### ๐Ÿ“ Tutorials + ### ๐Ÿ’ก Examples + ## ๐Ÿ“ˆ Roadmap + ## โค๏ธ Contributors + ## ๐Ÿ“œ License + ## โญ Acknowledgments + ``` + +### Development Themes + +=== ":material-api: API" + + API and microservices focused emojis. + + ```sh + readmeai --emojis api --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ```markdown + ## ๐Ÿ”Œ Table of Contents + ## ๐ŸŒ Overview + ## โšก Features + ## ๐Ÿ“ Project Structure + ### ๐Ÿ“‘ Project Index + ## ๐Ÿš€ Getting Started + ### ๐Ÿ“‹ Prerequisites + ### โš™๏ธ Installation + ### ๐Ÿ”‘ Authentication + ### ๐Ÿงช Testing + ## ๐Ÿ“ก Endpoints + ### ๐Ÿ” Queries + ### ๐Ÿ“ Mutations + ### ๐Ÿ”„ Subscriptions + ### ๐Ÿ”’ Authorization + ## โšก Performance + ### ๐Ÿ“Š Monitoring + ### ๐Ÿ” Tracing + ### ๐Ÿ“ˆ Metrics + ## ๐Ÿ›ฃ๏ธ Roadmap + ## ๐Ÿค Contributing + ## ๐Ÿ“œ License + ## โญ Acknowledgments + ``` + +=== ":material-web: Web" + + Web development focused emojis. + + ```sh + readmeai --emojis web --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ```markdown + ## ๐ŸŒ Table of Contents + ## ๐Ÿ’ป Overview + ## โœจ Features + ## ๐Ÿ“ Project Structure + ### ๐Ÿ“‘ Project Index + ## ๐Ÿš€ Getting Started + ### ๐Ÿ“‹ Prerequisites + ### โš™๏ธ Installation + ### ๐Ÿ–ฅ๏ธ Development + ### ๐Ÿงช Testing + ## ๐ŸŽจ Frontend + ### ๐Ÿงฉ Components + ### ๐Ÿ”„ State Management + ### ๐ŸŽฏ Routing + ### ๐Ÿ“ฑ Responsive Design + ## โšก Backend + ### ๐Ÿ›ข๏ธ Database + ### ๐Ÿ”Œ API + ### ๐Ÿ” Authentication + ### ๐Ÿ“ก WebSockets + ## ๐Ÿ“ฑ Mobile Support + ## ๐Ÿš€ Deployment + ### ๐Ÿ”„ CI/CD + ### ๐Ÿ“Š Monitoring + ### ๐Ÿ”’ Security + ## ๐Ÿ“ˆ Roadmap + ## ๐Ÿค Contributing + ## ๐Ÿ“œ License + ## โญ Acknowledgments + ``` + +=== ":material-cellphone: Mobile" + + Mobile development focused emojis. + + ```sh + readmeai --emojis mobile --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ```markdown + ## ๐Ÿ“ฑ Table of Contents + ## ๐ŸŒŸ Overview + ## โœจ Features + ## ๐Ÿ“ Project Structure + ### ๐Ÿ“‘ Project Index + ## ๐Ÿš€ Getting Started + ### ๐Ÿ“‹ Prerequisites + ### โš™๏ธ Installation + ### ๐Ÿ’ป Development + ### ๐Ÿงช Testing + ## ๐Ÿ“ฑ Platforms + ### ๐Ÿค– Android + ### ๐ŸŽ iOS + ### ๐ŸŒ Cross-Platform + ## ๐ŸŽจ UI/UX + ### ๐Ÿงฉ Components + ### ๐ŸŽฏ Navigation + ### ๐ŸŽจ Themes + ### ๐Ÿ“ฑ Responsive Design + ## ๐Ÿ“ก Backend + ### ๐Ÿ”Œ API Integration + ### ๐Ÿ’พ Data Storage + ### ๐Ÿ”„ Sync + ### ๐Ÿ“ถ Offline Support + ## ๐Ÿ“ฆ Distribution + ### ๐Ÿ—๏ธ Build + ### ๐Ÿ“ฒ Deploy + ### ๐Ÿ”„ Updates + ## ๐Ÿ“ˆ Analytics + ## ๐Ÿ›ฃ๏ธ Roadmap + ## ๐Ÿค Contributing + ## ๐Ÿ“œ License + ## โญ Acknowledgments + ``` + +> [๐Ÿšง WORK IN PROGRESS] - Need to add the remaining theme examples. + +## Configuration + +### Command-Line Options + +| Option | Description | Default | +| :----- | :---------- | :------ | +| `--emojis` | Specify emoji theme | `default` | + +### Creating Custom Themes + +You can create custom themes by adding them to your configuration: + +> [๐Ÿšง WORK IN PROGRESS] - Feature currently under development. + + + +## Best Practices + +### When to Use Emojis + +โœ… Recommended for: +- Open source projects +- Developer documentation +- Technical blogs +- Community resources +- Educational content + +โŒ Not recommended for: +- Enterprise documentation +- Legal documents +- Compliance materials +- Formal specifications + +### Theme Selection Guidelines + +1. **Match Project Domain** + - Choose themes that reflect your project's technology stack + - Use domain-specific themes for specialized projects + - Consider your target audience + +2. **Maintain Consistency** + - Use one theme throughout documentation + - Keep emoji usage consistent + - Follow theme patterns + +3. **Ensure Readability** + - Don't overuse emojis + - Test readability across platforms + - Consider color contrast + +4. **Consider Platform Support** + - Test emoji rendering + - Check platform compatibility + - Verify display across devices + +## FAQs + +??? question "Can I mix themes?" + While possible, it's recommended to stick to one theme for consistency. + +??? question "How do I preview themes?" + Use the `--dry-run` flag to preview theme output without generating a README. + +??? question "Can I disable emojis for specific sections?" + Yes, use the `--no-emoji` flag for specific sections in custom themes. + + + +## See Also + +- [Configuration Reference](cli_reference.md) +- [Header Styles Reference](components/headers.md) +- [Markdown Formatting Guide](guides/markdown.md) + +--- diff --git a/docs/docs/configuration/header.md b/docs/docs/components/header_styles.md similarity index 93% rename from docs/docs/configuration/header.md rename to docs/docs/components/header_styles.md index e6755057..979ea9ee 100644 --- a/docs/docs/configuration/header.md +++ b/docs/docs/components/header_styles.md @@ -2,11 +2,11 @@ title: "Headers" --- -# Headers +# Header Styles A header template style determines how your project's header section is structured and displayed in the README file. README-AI offers several pre-designed header styles to help brand your project and create a professional appearance. -## Header Style Options +## Available Styles !!! example @@ -14,6 +14,20 @@ A header template style determines how your project's header section is structur === "CLASSIC" + By default, the `classic` header style is used, so no additional option is needed. + +
+

Usage:

+ + ```sh + readmeai --repository https://github.com/username/project + ``` + +
+ +
+

Output:

+

README-AI-logo

@@ -29,7 +43,7 @@ A header template style determines how your project's header section is structur repo-top-language repo-language-count

-

Built with the tools and technologies:

+

Tech Stack

precommit Ruff @@ -46,6 +60,7 @@ A header template style determines how your project's header section is structur Google%20Gemini Pydantic

+
@@ -53,25 +68,21 @@ A header template style determines how your project's header section is structur
  • - โ€ข Centered alignment
  • - โ€ข Logo above project name
  • - โ€ข Traditional README layout
  • - โ€ข Ideal for most projects
    • @@ -80,6 +91,18 @@ A header template style determines how your project's header section is structur === "COMPACT" +
    +

    Usage:

    + + ```sh + readmeai --header-style compact --repository https://github.com/username/project + ``` + +
    + +
    +

    Output:

    +
    @@ -93,8 +116,8 @@ A header template style determines how your project's header section is structur repo-top-language repo-language-count

    -

    Built with the tools and technologies:

    -

    +

    Tech Stack

    +

    Streamlit precommit Ruff @@ -105,6 +128,7 @@ A header template style determines how your project's header section is structur

    +

    @@ -113,25 +137,21 @@ A header template style determines how your project's header section is structur
    • - โ€ข Left-aligned layout
    • - โ€ข Logo and title on same line
    • - โ€ข Space-efficient design
    • - โ€ข Perfect for smaller README files
      • @@ -140,6 +160,17 @@ A header template style determines how your project's header section is structur === "MODERN" +
      +

      Usage:

      + + ```sh + readmeai --header-style modern --repository https://github.com/username/project + ``` + +
      + +
      +

      Output:

      PYFLINK-POC

      @@ -152,7 +183,7 @@ A header template style determines how your project's header section is structur repo-top-language repo-language-count

      -

      Built with the tools and technologies:

      +

      Tech Stack

      GNU%20Bash Python @@ -162,6 +193,8 @@ A header template style determines how your project's header section is structur Apache%20Flink

      +
      +
      @@ -170,25 +203,21 @@ A header template style determines how your project's header section is structur
      • - โ€ข Left-aligned text
      • - โ€ข Logo floated to the right
      • - โ€ข Contemporary asymmetric design
      • - โ€ข Great for documentation sites
        • @@ -197,6 +226,18 @@ A header template style determines how your project's header section is structur === "SVG" +
        +

        Usage:

        + + ```sh + readmeai --header-style svg --repository https://github.com/username/project + ``` + +
        + +
        +

        Output:

        +

        readme-ai-banner

        @@ -209,7 +250,7 @@ A header template style determines how your project's header section is structur repo-top-language repo-language-count

        -

        Built with the tools and technologies:

        +

        Tech Stack

        Anthropic precommit @@ -227,6 +268,7 @@ A header template style determines how your project's header section is structur Google%20Gemini Pydantic

        +

        @@ -235,25 +277,21 @@ A header template style determines how your project's header section is structur
        • - โ€ข Full-width SVG banner support
        • - โ€ข Centered alignment
        • - โ€ข Scalable vector graphics
        • - โ€ข Ideal for custom branding
          • @@ -262,6 +300,18 @@ A header template style determines how your project's header section is structur === "ASCII" +
          +

          Usage:

          + + ```sh + readmeai --header-style ascii --repository https://github.com/username/project + ``` + +
          + +
          +

          Output:

          + 
           		โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ   โ–ˆโ–ˆ   โ–ˆโ–ˆโ–ˆโ–ˆ   โ–ˆโ–ˆ   โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ          โ–ˆโ–ˆ   โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ
@@ -280,7 +330,7 @@ A header template style determines how your project's header section is structur
 			repo-top-language
 			repo-language-count
 		
          
-		
          Built with the tools and technologies:
          
+		
          Tech Stack
          
 		
          
 			Anthropic
 			precommit
@@ -298,6 +348,7 @@ A header template style determines how your project's header section is structur
 			Google%20Gemini
 			Pydantic
 		
          
+

          @@ -306,25 +357,21 @@ A header template style determines how your project's header section is structur
          • - โ€ข Text-based art logo
          • - โ€ข Minimal and retro style
          • - โ€ข No image dependencies
          • - โ€ข Good for terminal-focused tools
            • @@ -334,6 +381,18 @@ A header template style determines how your project's header section is structur === "ASCII_BOX" +
            +

            Usage:

            + + ```sh + readmeai --header-style ascii_box --repository https://github.com/username/project + ``` + +
            + +
            +

            Output:

            + 
             		โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
@@ -357,7 +416,7 @@ A header template style determines how your project's header section is structur
 			repo-top-language
 			repo-language-count
 		
            
-		
            Built with the tools and technologies:
            
+		
            Tech Stack
            
 		
            
 			Anthropic
 			precommit
@@ -375,6 +434,7 @@ A header template style determines how your project's header section is structur
 			Google%20Gemini
 			Pydantic
 		
            
+

            @@ -383,25 +443,21 @@ A header template style determines how your project's header section is structur
            • - โ€ข Text-based art logo
            • - โ€ข Minimal and retro style
            • - โ€ข No image dependencies
            • - โ€ข Good for terminal-focused tools
              • @@ -415,7 +471,7 @@ README-AI provides several ways to customize your header style: 1. **Default Styles**: Choose from pre-defined header layouts 2. **Alignment Options**: Set text and image alignment 3. **Custom Sizing**: Adjust logo and image dimensions -4. **Badge Integration**: Incorporates shield badges and tech stack icons +4. **Badge Integration**: Incorporates shield badges and Tech Stack icons The selected style will determine how your project's name, logo, description, and badges are arranged in the header section. @@ -501,7 +557,7 @@ This will prepend relevant emojis to each section header, enhancing the visual a To customize the header template, you can initialize the `HeaderTemplate` class and pass your preferred style (`classic`, `compact`, or `modern`). Here's an example: ```python -from readmeai.templates.header import HeaderTemplate, HeaderStyleOptions +from readmeai.generators.headers import HeaderTemplate, HeaderStyleOptions # Initialize the template with the desired style header_template = HeaderTemplate(style=HeaderStyleOptions.MODERN) @@ -512,7 +568,7 @@ data = { "image": "https://example.com/logo.png", "image_width": "100px", "repo_name": "My Awesome Project", - "slogan": "Building the future, one commit at a time.", + "tagline": "Building the future, one commit at a time.", "shields_icons": "", "badges_tech_stack": "", } diff --git a/docs/docs/components/project_badges.md b/docs/docs/components/project_badges.md new file mode 100644 index 00000000..2f904df3 --- /dev/null +++ b/docs/docs/components/project_badges.md @@ -0,0 +1,204 @@ +--- +title: Badges +--- + +## Overview + +Badges are simple embeddable icons that display various metrics about your project, such as the number of stars, forks, languages used, CI/CD build status, test coverage, and license. They provide quick information to users and visitors. + +Use the `--badge-style` option to customize your project's badges: + +```sh +readmeai --badge-style --repository +``` + +## Badge Types + +### Default Badges +- License status +- Last commit timestamp +- Primary programming language +- Total languages count + +### Project Badges +- Dependencies and frameworks +- Build status +- Test coverage +- Version information + +## Available Styles + +Use the `--badge-style` option to select from the following styles: + +=== "Default" + + The default badge set includes the project `license`, `last commit`, `top language`, and `total languages`. The *project badge* set is not included. No additional options are required, as this is the default behavior. + + ```sh + readmeai --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Default Badge](https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white) + ![Default Badge](https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white) + ![Default Badge](https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff) + ![Default Badge](https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff) + +=== "Flat" + + ```sh + readmeai --badge-style flat --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Flat Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white) + +=== "Flat-Square" + + ```sh + readmeai --badge-style flat-square --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Flat-Square Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white) + +=== "For-The-Badge" + + ```sh + readmeai --badge-style for-the-badge --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![For-the-Badge Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white) + +=== "plastic" + + ```sh + readmeai --badge-style plastic --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Plastic Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white) + +=== "Skills" + + ```sh + readmeai --badge-style skills --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Skills Badge](https://skillicons.dev/icons?i=py) + +=== "skills-light" + + ```sh + readmeai --badge-style skills-light --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Skills-Light Badge](https://skillicons.dev/icons?i=py&theme=light) + +=== "social" + + ```sh + readmeai --badge-style social --repository https://github.com/username/project + ``` + + !!! example "Output Preview" + + ![Social Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=FFD845) + +## How It Works + +README-AI automatically detects your project's dependencies and technologies during the repository ingestion process. It then uses these dependencies and technologies to generate a comprehensive list of relevant badges for your project. + +When you provide the `--badge-style` option to the `readmeai` command, two sets of badges are generated: + +1. **Default Metadata Badges**: The default set is always included in the generated README file. The default badges include the project `license`, `last commit`, `top language`, and `total languages`. +2. **Project Dependency Badges**: When the `--badge-style` argument is provided to the CLI, a second badge set is generated, representing the extracted dependencies and metadata from your codebase. + +The badge sets are formatted in the README header and provide the reader with a quick overview of the project's key metrics and technologies. + +## Examples + +### Basic Usage +```sh +readmeai --badge-style flat --repository https://github.com/username/project +``` + +### Custom Colors +```sh +readmeai --badge-color orange --badge-style flat-square --repository https://github.com/username/project +``` + +### Combined Options + +Next, let's combine the `--badge-color` and `--badge-style` options to generate a README with custom badge colors and styles. + +```sh +readmeai --badge-color orange \ + --badge-style flat-square \ + --repository https://github.com/eli64s/readme-ai +``` + +!!! example "Output Preview" + + {{ PROJECT-NAME }} + + {{ PROJECT-DESCRIPTION }} + + ![License](https://img.shields.io/github/license/eli64s/readme-ai?style=flat-square&color=orange&logo=opensourceinitiative&logoColor=white) + ![Last Commit](https://img.shields.io/github/last-commit/eli64s/readme-ai?style=flat-square&color=orange&logo=git&logoColor=white) + ![Top Language](https://img.shields.io/github/languages/top/eli64s/readme-ai?style=flat-square&color=orange) + ![Language Count](https://img.shields.io/github/languages/count/eli64s/readme-ai?style=flat-square&color=orange) + + Tech Stack + + ![pre-commit](https://img.shields.io/badge/precommit-FAB040.svg?style=flat-square&logo=pre-commit&logoColor=black) + ![Ruff](https://img.shields.io/badge/Ruff-FCC21B.svg?style=flat-square&logo=Ruff&logoColor=black) + ![GNU Bash](https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat-square&logo=GNU-Bash&logoColor=white) + ![Pytest](https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white) + ![Docker](https://img.shields.io/badge/Docker-2496ED.svg?style=flat-square&logo=Docker&logoColor=white) + ![Python](https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white) + ![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white) + ![Poetry](https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white) + ![AIOHTTP](https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=flat-square&logo=AIOHTTP&logoColor=white) + ![Material for MkDocs](https://img.shields.io/badge/Material%20for%20MkDocs-526CFE.svg?style=flat-square&logo=Material-for-MkDocs&logoColor=white) + ![OpenAI](https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white) + ![Google Gemini](https://img.shields.io/badge/Google%20Gemini-8E75B2.svg?style=flat-square&logo=Google-Gemini&logoColor=white) + ![Pydantic](https://img.shields.io/badge/Pydantic-E92063.svg?style=flat-square&logo=Pydantic&logoColor=white) + +!!! note + 1. The badge color can be specified using a hex code or color name. + a. `--badge-color orange` + b. `--badge-color #0080ff` + 2. The `--badge-color` option only affects default badges, while `--badge-style` applies to all badges. + +## Style Guidelines + +### Best Practices + +- **Complementary**: Choose a style that complements your project's overall design. +- **Relevancy**: Use badges to highlight relevant information about your project. +- **Overcrowding**: Too many can clutter your README and make it hard to read. +- **Customize**: Consider using custom badges for project-specific metrics. +- **Accuracy**: Ensure that all badge links are correct and up-to-date. + +## Credits + +Badge services provided by: + +- [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) + +--- diff --git a/docs/docs/configuration/project_logo.md b/docs/docs/components/project_logo.md similarity index 98% rename from docs/docs/configuration/project_logo.md rename to docs/docs/components/project_logo.md index 5b4899c9..8a6bf27e 100644 --- a/docs/docs/configuration/project_logo.md +++ b/docs/docs/components/project_logo.md @@ -1,8 +1,10 @@ -# Project Logo +--- +title: Project Logo +--- A project logo is a visual representation of your project that appears at the top of your README file. It helps to brand your project and make it more recognizable. README-AI offers various options for adding a logo to your project's README. -## Default Options +## Default Logo Options Use the `--image` option to select from the following logo styles: @@ -116,3 +118,5 @@ This will generate a unique logo that you can display in your project's document - 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. + +--- diff --git a/docs/docs/configuration/table_of_contents.md b/docs/docs/components/table_of_contents.md similarity index 99% rename from docs/docs/configuration/table_of_contents.md rename to docs/docs/components/table_of_contents.md index feb1f255..fdf4a63c 100644 --- a/docs/docs/configuration/table_of_contents.md +++ b/docs/docs/components/table_of_contents.md @@ -84,3 +84,5 @@ readmeai --toc-style number \ --badge-style flat \ --repository https://github.com/username/project ``` + +--- diff --git a/docs/docs/configuration/badges.md b/docs/docs/configuration/badges.md deleted file mode 100644 index aa6af20b..00000000 --- a/docs/docs/configuration/badges.md +++ /dev/null @@ -1,117 +0,0 @@ -# Badges - -A badge is a simple embeddable icon that displays various metrics such as the number of stars or forks for a repository, languages used in the project, CI/CD build status, test coverage, the license of the project, and more. Badges are a great way to provide quick information about your project to users and visitors. - -README-AI offers various badge styles to enhance your project's README. This guide explains how to use and customize these badges. - -## Badge Styles - -Use the `--badge-style` option to select from the following styles: - -=== "default" - - ![Default Badge](https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white) - ![Default Badge](https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white) - ![Default Badge](https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff) - ![Default Badge](https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff) - -=== "flat" - - ![Flat Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white) - -=== "flat-square" - - ![Flat-Square Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white) - -=== "for-the-badge" - - ![For-the-Badge Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white) - -=== "plastic" - - ![Plastic Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white) - -=== "skills" - - ![Skills Badge](https://skillicons.dev/icons?i=py) - -=== "skills-light" - - ![Skills-Light Badge](https://skillicons.dev/icons?i=py&theme=light) - -=== "social" - - ![Social Badge](https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=FFD845) - -## How It Works - -README-AI automatically detects your project's dependencies and technologies during the repository ingestion process. It then uses these dependencies and technologies to generate a comprehensive list of relevant badges for your project. - -When you provide the `--badge-style` option to the `readmeai` command, two sets of badges are generated: - -1. **Default Metadata Badges**: The default set is always included in the generated README file. The default badges include the project `license`, `last commit`, `top language`, and `total languages`. -2. **Project Dependency Badges**: When the `--badge-style` argument is provided to the CLI, a second badge set is generated, representing the extracted dependencies and metadata from your codebase. - -The badge sets are formatted in the README header and provide the reader with a quick overview of the project's key metrics and technologies. - -## Usage - -Let's generate a README with custom badge colors and styles using the `--badge-color` and `--badge-style` options: - -```sh -readmeai --badge-color orange \ - --badge-style flat-square \ - --repository https://github.com/eli64s/readme-ai -``` - -The command above generates a README with the following badge configuration: - -!!! example - - === "Badge Generation" - - - ![License](https://img.shields.io/github/license/eli64s/readme-ai?style=flat-square&color=orange&logo=opensourceinitiative&logoColor=white) - ![Last Commit](https://img.shields.io/github/last-commit/eli64s/readme-ai?style=flat-square&color=orange&logo=git&logoColor=white) - ![Top Language](https://img.shields.io/github/languages/top/eli64s/readme-ai?style=flat-square&color=orange) - ![Language Count](https://img.shields.io/github/languages/count/eli64s/readme-ai?style=flat-square&color=orange) - - *Built with the tools and technologies:* - - ![pre-commit](https://img.shields.io/badge/precommit-FAB040.svg?style=flat-square&logo=pre-commit&logoColor=black) - ![Ruff](https://img.shields.io/badge/Ruff-FCC21B.svg?style=flat-square&logo=Ruff&logoColor=black) - ![GNU Bash](https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat-square&logo=GNU-Bash&logoColor=white) - ![Pytest](https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white) - ![Docker](https://img.shields.io/badge/Docker-2496ED.svg?style=flat-square&logo=Docker&logoColor=white) - ![Python](https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white) - ![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white) - ![Poetry](https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white) - ![AIOHTTP](https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=flat-square&logo=AIOHTTP&logoColor=white) - ![Material for MkDocs](https://img.shields.io/badge/Material%20for%20MkDocs-526CFE.svg?style=flat-square&logo=Material-for-MkDocs&logoColor=white) - ![OpenAI](https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white) - ![Google Gemini](https://img.shields.io/badge/Google%20Gemini-8E75B2.svg?style=flat-square&logo=Google-Gemini&logoColor=white) - ![Pydantic](https://img.shields.io/badge/Pydantic-E92063.svg?style=flat-square&logo=Pydantic&logoColor=white) - - -The `--badge-color` option **only** modifies the default badge set, while the `--badge-style` option is applied to **both** the default and project dependency badges - - -## Tips for Using Badges - -- Choose a badge style that complements your project's overall design. -- Use badges to highlight relevant information about your project, such as license, build status, and test coverage. -- Don't overuse badges โ€“ too many can clutter your README and make it hard to read. -- Ensure that all badge links are correct and up-to-date. -- Consider using custom badges for project-specific information or metrics. - -## References - -Thank you to the following resources for providing open-source badges and icons: - -* [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) - ---- diff --git a/docs/docs/configuration/emojis.md b/docs/docs/configuration/emojis.md deleted file mode 100644 index b91450fd..00000000 --- a/docs/docs/configuration/emojis.md +++ /dev/null @@ -1,27 +0,0 @@ -# Emojis - -(๐Ÿšง work in progress ๐Ÿšง) - -Emojis are a fun way to add some personality to your README.md file. README-AI allows you to automatically add emojis to all headers in the generated README file by providing the `--emojis` option to the `readmeai` command. - -## How It Works - -When you provide the `--emojis` option to the `readmeai` command, README-AI automatically adds emojis to all headers in the generated README file. - -=== "Emojis Enabled" - - (๐Ÿšง work in progress ๐Ÿšง) - -=== "Emojis Disabled (default)" - - (๐Ÿšง work in progress ๐Ÿšง) - -## Usage - -To enable emojis in the generated README file, use the `--emojis` option when running the `readmeai` command: - -```sh -readmeai --repository --emojis -``` - ---- diff --git a/docs/docs/examples/documentation-examples.md b/docs/docs/examples/documentation-examples.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/examples/profile-readmes.md b/docs/docs/examples/profile-readmes.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/examples/readme-templates.md b/docs/docs/examples/readme-templates.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/llms/anthropic.md b/docs/docs/llms/anthropic.md index dd9b83bc..e69de29b 100644 --- a/docs/docs/llms/anthropic.md +++ b/docs/docs/llms/anthropic.md @@ -1,106 +0,0 @@ - diff --git a/docs/docs/llms/google_gemini.md b/docs/docs/llms/google_gemini.md index 105c69ad..e69de29b 100644 --- a/docs/docs/llms/google_gemini.md +++ b/docs/docs/llms/google_gemini.md @@ -1,19 +0,0 @@ - diff --git a/docs/docs/llms/offline_mode.md b/docs/docs/llms/offline_mode.md index 0cb36849..e69de29b 100644 --- a/docs/docs/llms/offline_mode.md +++ b/docs/docs/llms/offline_mode.md @@ -1,18 +0,0 @@ - diff --git a/docs/docs/llms/ollama.md b/docs/docs/llms/ollama.md index f9797383..e69de29b 100644 --- a/docs/docs/llms/ollama.md +++ b/docs/docs/llms/ollama.md @@ -1,27 +0,0 @@ - diff --git a/docs/docs/llms/openai.md b/docs/docs/llms/openai.md index 52fef885..e69de29b 100644 --- a/docs/docs/llms/openai.md +++ b/docs/docs/llms/openai.md @@ -1,20 +0,0 @@ - diff --git a/docs/docs/usage/cli.md b/docs/docs/usage/cli.md index 0d579d01..41950b29 100644 --- a/docs/docs/usage/cli.md +++ b/docs/docs/usage/cli.md @@ -1,94 +1,80 @@ ---- -title: "Running the CLI" ---- +# ๐Ÿšง Language Model Integrations -Let's explore how to run `readmeai` with various configurations and custom options. We'll start with the basic usage and then move on to more advanced options. +*๐Ÿšง WIP* -## Basic Usage +Readme-ai integrates seamlessly with various Large Language Model (LLM) services to generate high-quality README content. This page provides an overview of the supported LLM services and links to detailed information about each. -The general syntax for using readme-ai is: +## Supported LLM Services -```sh -readmeai --repository --api [OPTIONS] -``` +1. [OpenAI](openai.md) +2. [Ollama](ollama.md) +3. [Anthropic](anthropic.md) +4. [Google Gemini](google_gemini.md) +5. [Offline Mode](offline_mode.md) -Replace `` with your repository URL or local path, and `` with your chosen LLM service (openai, ollama, gemini, or offline). +## Comparing LLM Services -## Examples with Different LLM Providers +| Service | Pros | Cons | +|---------|------|------| +| OpenAI | High-quality output, Versatile | Requires API key, Costs associated | +| Ollama | Free, Privacy-focused, Offline | May be slower, Requires local setup | +| Anthropic | Privacy-focused, Offline | May be slower, Requires local setup | +| Gemini | Strong performance, Google integration | Requires API key | +| Offline | No internet required, Fast | Basic output, Limited customization | -### Using OpenAI +--- -```sh -readmeai --repository https://github.com/eli64s/readme-ai \ - --api openai \ - --model gpt-3.5-turbo # (1) -``` + diff --git a/docs/docs/usage/docker.md b/docs/docs/usage/docker.md index 7d49797a..3fd5df2f 100644 --- a/docs/docs/usage/docker.md +++ b/docs/docs/usage/docker.md @@ -113,3 +113,5 @@ docker rmi zeroxeli/readme-ai:latest 3. For network-related issues, verify your internet connection and firewall settings. For more detailed troubleshooting, refer to the official [Docker documentation](https://docs.docker.com/config/daemon/#troubleshoot-the-daemon) or [open an issue](https://github.com/eli64s/readme-ai/issues) on GitHub. + +--- diff --git a/docs/docs/usage/environment.md b/docs/docs/usage/environment.md index e933f065..daf1a6e3 100644 --- a/docs/docs/usage/environment.md +++ b/docs/docs/usage/environment.md @@ -46,3 +46,5 @@ export GOOGLE_API_KEY= !!! note "Unsupported Language Models" If your preferred LLM API is not supported, open an [issue](https://github.com/eli64s/readme-ai/issues) or submit a [pull request](https://github.com/eli64s/readme-ai/pulls) and we'll review the request! + +--- diff --git a/docs/docs/usage/installation.md b/docs/docs/usage/installation.md index 8ff5669d..6c3366d8 100644 --- a/docs/docs/usage/installation.md +++ b/docs/docs/usage/installation.md @@ -76,3 +76,5 @@ You should see the installed version of `readmeai` displayed in the output: ```sh readmeai version 0.5.99 ``` + +--- diff --git a/docs/docs/usage/prerequisites.md b/docs/docs/usage/prerequisites.md deleted file mode 100644 index fe3797e5..00000000 --- a/docs/docs/usage/prerequisites.md +++ /dev/null @@ -1,29 +0,0 @@ -# Prerequisites - -### System Requirements - -- **Python**: `3.9+` -- **Package Manager/Container**: `pip`, `pipx`, `uv`, or `docker`. - -### Supported Sources - -The following git hosting services are supported for source code retrieval, along with your local file system: - -- [**GitHub**](https://github.com/) -- [**GitLab**](https://gitlab.com/) -- [**Bitbucket**](https://bitbucket.org/) -- [**File System**](https://en.wikipedia.org/wiki/File_system) - -If your Git provider is not listed, open an [issue](https://github.com/eli64s/readme-ai/issues) or submit a [pull request](https://github.com/eli64s/readme-ai/pulls) to add support for additional platforms. - -### Supported LLM APIs - -To enable the full functionality of `readmeai`, an account and API key are required for one of the following providers: - -- [**OpenAI**](https://platform.openai.com/docs/quickstart/account-setup): Recommended for general use. Requires an OpenAI account and API key. -- [**Ollama**](https://github.com/ollama/ollama): Free and open-source. No API key required. -- [**Anthropic**](https://www.anthropic.com/): Requires an Anthropic account and API key. -- [**Google Gemini**](https://ai.google.dev/tutorials/python_quickstart): Requires a Google Cloud account and API key. -- [**Offline Mode**](https://github.com/eli64s/readme-ai/blob/main/examples/readme-offline.md): Generates a boilerplate README without making API calls. - -For more information on setting up an API key, refer to the provider's documentation. diff --git a/docs/docs/usage/python.md b/docs/docs/usage/python.md index ab688cba..910f5ec1 100644 --- a/docs/docs/usage/python.md +++ b/docs/docs/usage/python.md @@ -103,3 +103,5 @@ For additional help: - Check the [GitHub Issues](https://github.com/eli64s/readme-ai/issues) - Visit the [Official Documentation](https://eli64s.github.io/readme-ai/) - Start a [Discussion](https://github.com/eli64s/readme-ai/discussions) + +--- diff --git a/docs/docs/usage/streamlit.md b/docs/docs/usage/streamlit.md index 9babb758..1114c087 100644 --- a/docs/docs/usage/streamlit.md +++ b/docs/docs/usage/streamlit.md @@ -12,3 +12,5 @@ For more information about the Streamlit app, see the [readme-ai-streamlit](http !!! warning "Streamlit App Status" The Streamlit web app for readme-ai is not actively developed and may not be up-to-date with the latest features. For the most recent version of readme-ai, please use the command-line interface. + +--- diff --git a/docs/docs/usage/system-requirements.md b/docs/docs/usage/system-requirements.md new file mode 100644 index 00000000..790e1c78 --- /dev/null +++ b/docs/docs/usage/system-requirements.md @@ -0,0 +1,72 @@ +--- +title: "System Requirements" +description: "Detailed guide on system requirements, supported repository sources, and LLM API providers for README-AI" +--- + +This guide outlines the necessary system requirements and compatibility information for using `readmeai` effectively. + +## Core Requirements + +- **Python Version**: `3.9` or higher +- **Package Management/Conainter Runtime**: Choose one of the following: + - [`pip`][pip]: Python's default package installer, recommended for most users. + - [`pipx`][pipx]: Install and run `readmeai` in an isolated environment. + - [`uv`][uv]: Fastest way to install `readmeai` with a single command. + - [`docker`][docker]: Run `readmeai` in a containerized environment. + +## Supported Repository Sources + +The `readmeai` CLI can retrieve source code from the following Git hosting services or your local file system: + +| Platform | Description | Resource | +| :------- | :---------- | :--- | +| File System | Access repositories on your machine | [Learn more][file-system] | +| GitHub | World's largest code hosting platform | [GitHub.com][github] | +| GitLab | Complete DevOps platform | [GitLab.com][gitlab] | +| Bitbucket | Atlassian's Git solution | [Bitbucket.org][bitbucket] | + +!!! note + Missing a Git provider? [open an issue][issues] or [submit a pull request][pulls] to help us expand our platform support. + +## Supported LLM API Providers + +To unlock the full potential of `readmeai`, you'll need an account and API key from one of the providers below: + +| Provider | Description | Resource | +|----------|-------------|-------| +| OpenAI | Recommended for general use | [OpenAI Developer quickstart][openai] | +| Anthropic | Advanced language models | [Anthropic Developer docs][anthropic] | +| Google Gemini | Google's multimodal AI model | [Gemini API quickstart][gemini] | +| Ollama | Free and open-source (No API key required) | [Ollama GitHub repository][ollama] | +| Offline Mode | Run `readmeai` without a LLM API | [Example offline mode README][offline-mode] | + +## Next Steps + +- [Installation](installation.md): Learn how to install `readmeai` +- [CLI Reference](cli.md): Discover how to use `readmeai` effectively +- [Troubleshooting](../troubleshooting.md): Find solutions to common issues + +--- + + +[openai]: https://platform.openai.com/docs/quickstart/account-setup: "OpenAI Developer quickstart" +[anthropic]: https://docs.anthropic.com/en/home "Anthropic Developer docs" +[gemini]: https://ai.google.dev/tutorials/python_quickstart "Gemini API quickstart" +[ollama]: https://github.com/ollama/ollama "Ollama GitHub repository" +[offline-mode]: https://github.com/eli64s/readme-ai/blob/main/examples/offline-mode/readme-litellm.md "Example offline mode README" + + +[pip]: https://pip.pypa.io/en/stable/ "pip" +[pipx]: https://pipx.pypa.io/stable/ "pipx" +[uv]: https://docs.astral.sh/uv/ "uv" +[docker]: https://docs.docker.com/ "docker" + + +[file-system]: https://en.wikipedia.org/wiki/File_system "Learn more" +[github]: https://github.com/ "GitHub.com" +[gitlab]: https://gitlab.com/ "GitLab.com" +[bitbucket]: https://bitbucket.org/ "Bitbucket.org" + + +[issues]: https://github.com/eli64s/readme-ai/issues "open an issue" +[pulls]: https://github.com/eli64s/readme-ai/pulls) "submit a pull request" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index dec68631..ffa8af96 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -34,142 +34,188 @@ theme: example: octicons/beaker-16 quote: octicons/quote-16 features: - - announce.dismiss - - content.action.edit - - content.action.view - - content.code.annotate - - content.code.copy - - content.code.select - - content.tabs.link - - content.tooltips - - header.autohide - - navigation.expand - - navigation.footer - - navigation.indexes - - navigation.instant - - navigation.instant.prefetch - - navigation.instant.progress - - navigation.prune - - navigation.sections - - navigation.tabs - - navigation.top - - navigation.tracking - - search.highlight - - search.share - - search.suggest - - toc.follow + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.tabs.link + - content.tooltips + - header.autohide + - navigation.expand + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow palette: - - scheme: light - primary: white - accent: deep-purple - toggle: - icon: material/brightness-7 - name: Switch to light mode - - scheme: dark - primary: black - accent: deep-purple - toggle: - icon: material/brightness-4 - name: Switch to dark mode + - scheme: light + primary: white + accent: deep-purple + toggle: + icon: material/brightness-7 + name: Switch to light mode + - scheme: dark + primary: black + accent: deep-purple + toggle: + icon: material/brightness-4 + name: Switch to dark mode + markdown_extensions: - - admonition - - attr_list - - def_list - - md_in_html - - codehilite - - toc: - permalink: true - - pymdownx.arithmatex: - generic: true - - pymdownx.betterem: - 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 - pygments_lang_class: true - - pymdownx.inlinehilite - - pymdownx.keys - - pymdownx.magiclink: - repo_url_shorthand: true - user: eli64s - repo: readme-ai - - pymdownx.mark - - pymdownx.smartsymbols - - pymdownx.superfences: - custom_fences: - - name: mermaid - class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format - - pymdownx.tabbed: - alternate_style: true - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tilde +- admonition +- attr_list +- def_list +- md_in_html +- codehilite +- toc: + permalink: true +- pymdownx.arithmatex: + generic: true +- pymdownx.betterem: + 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 + pygments_lang_class: true +- pymdownx.inlinehilite +- pymdownx.keys +- pymdownx.magiclink: + repo_url_shorthand: true + user: eli64s + repo: readme-ai +- pymdownx.mark +- pymdownx.smartsymbols +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format "" +- pymdownx.tabbed: + alternate_style: true +- pymdownx.tasklist: + custom_checkbox: true +- pymdownx.tilde plugins: - - search - - social - - git-revision-date-localized: - type: date - - minify: - minify_html: true +- search +- social +- git-revision-date-localized: + type: date +- minify: + minify_html: true nav: - - Introduction: - - index.md - - Why README-AI?: why.md - - Getting Started: usage/prerequisites.md - - Getting Help: troubleshooting.md - - Contributing: contributing.md - # - Philosophy: philosophy.md - - Getting Started: - - Prerequisites: usage/prerequisites.md - - Installation: usage/installation.md - - Environment: usage/environment.md - - Usage: - - CLI: usage/cli.md - # - Python: usage/python.md - - Docker: usage/docker.md - - Streamlit: usage/streamlit.md - - Customize: - - Components: - - Badges: configuration/badges.md - - Headers: configuration/header.md - - Project Logo: configuration/project_logo.md - - Table of Contents: configuration/table_of_contents.md - - Emojis: configuration/emojis.md - # - Themes: guides/themes.md - # - Palettes: guides/palettes.md - # - Fonts: guides/fonts.md - # - Icons: guides/icons.md - - AI Integration: - - llms/index.md - - Cloud Hosted: - - OpenAI: llms/openai.md - - Anthropic: llms/anthropic.md - - Google Gemini: llms/google_gemini.md - - Local Hosted: - - Ollama: llms/ollama.md - - Offline Mode: llms/offline_mode.md - - CLI Reference: - - cli.md - - Guides: - - Best Practices: guides/best_practices.md - - Custom Templates: guides/custom_templates.md - - Markdown: guides/markdown.md - - Examples: - - Gallery: examples/gallery.md - # - Use Cases: examples/use-cases.md +- Welcome: + - index.md + - Why Choose README-AI?: why.md + - Contributing to README-AI: contributing.md + - Troubleshooting & Support: troubleshooting.md +- Getting Started: + - System Requirements: usage/system-requirements.md + - Installation Guide: usage/installation.md + - Environment Setup: usage/environment.md + - Using README-AI: + - Command-Line Interface: usage/cli.md + - Docker Container: usage/docker.md + - Streamlit Web App: usage/streamlit.md +- Components: + - Badges: components/project_badges.md + - Headers: components/header_styles.md + - Emoji Themes: components/emoji_themes.md + - Project Logo: components/project_logo.md + - Table of Content: components/table_of_contents.md + - Models: + - llms/index.md + - Paid LLM APIs: + - OpenAI: llms/openai.md + - Anthropic: llms/anthropic.md + - Google Gemini: llms/google_gemini.md + - Open Source LLMs: + - Ollama: llms/ollama.md + - Offline Mode: + - Offline Mode: llms/offline_mode.md +- CLI Reference: cli-reference.md +- Examples: + - README Gallery: examples/gallery.md + # - Sample README Templates: examples/readme-templates.md + # - Documentation Examples: examples/documentation-examples.md + # - GitHub Profile READMEs: examples/profile-readmes.md +- Markdown Cookbook: + - Introduction: guides/markdown/index.md + - Syntax: + - Headings & Paragraphs: guides/markdown/headings-paragraphs.md + - Text Formatting: guides/markdown/text-formatting.md + - Lists: guides/markdown/lists.md + - Links: + - Inline Links: guides/markdown/links/inline-links.md + - Reference Links: guides/markdown/links/reference-links.md + - Images & Media: + - Center Images: guides/markdown/images/centered-images.md + - Align Images: guides/markdown/images/aligned-images.md + - Small Images & Icons: guides/markdown/images/small-images.md + - Text Boxes: guides/markdown/images/text-boxes.md + - Text Wrapping: guides/markdown/images/text-wrapping.md + - Advanced: + - Tables: + - Alignment: guides/markdown/tables/alignment.md + - Multi-Line Cells: guides/markdown/tables/multi-line-cells.md + - Task Lists in Tables: guides/markdown/tables/task-lists.md + - Merge Cells: guides/markdown/tables/merged-cells.md + - Text Styling: + - Formatting: guides/markdown/text-styling/basic-formatting.md + - Progress Bars: guides/markdown/text-styling/progress-bars.md + - Highlight Text: guides/markdown/text-styling/highlighting.md + - Underline Text: guides/markdown/text-styling/underlining.md + - Code Blocks: guides/markdown/code-blocks.md + - Blockquotes & Callouts: guides/markdown/blockquotes.md + - Task Lists: guides/markdown/task-lists.md + - Footnotes & Citations: guides/markdown/footnotes.md + - Buttons & Shortcuts: guides/markdown/buttons-and-shortcuts.md + - Contact Info: guides/markdown/contact-info.md + - Contributing Guidelines: guides/markdown/contributing.md + - HTML Elements: + - Spacing Entities: guides/markdown/html-elements/spacing-entities.md + - GitHub Markdown: + - GitHub Features: guides/markdown/github-flavored.md + - Emojis & Icons: guides/markdown/emoji-icons.md + - Issues & PRs: guides/markdown/issue-references.md + - Documentation: + - Table of Contents: guides/markdown/table-of-contents.md + - Diagrams & Flowcharts: guides/markdown/mermaid-diagrams.md + - Math Equations: guides/markdown/math-equations.md + - Styling: + - Custom Styling: guides/markdown/styling-and-layout/custom-styling.md + - Buttons & Badges: guides/markdown/styling-and-layout/buttons-badges.md + - Layout Techniques: guides/markdown/styling-and-layout/layout-techniques.md + - Best Practices: + - Effective READMEs: guides/markdown/best-practices/effective-readmes.md + - Organizing Docs: guides/markdown/best-practices/doc-structure.md + - Accessibility: guides/markdown/best-practices/accessibility.md + - Tools & Resources: + - Markdown Editors: guides/markdown/resources/editors-ides.md + - Extensions: guides/markdown/resources/extensions.md + - Linting Tools: guides/markdown/resources/linting-formatting.md extra_css: - - css/extra.css +- css/extra.css extra_javascript: - - js/extra.js +- js/extra.js extra: analytics: provider: google @@ -177,18 +223,18 @@ extra: feedback: title: Was this page helpful? ratings: - - icon: material/emoticon-happy-outline - name: This page was helpful - data: 1 - note: Thanks for your feedback! - - icon: material/emoticon-sad-outline - name: This page could be improved - data: 0 - note: Thanks for your feedback! Help us improve by using our feedback form. + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: Thanks for your feedback! Help us improve by using our feedback form. 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 + - 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 diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 3e0c7a61..b84f3a33 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -1,25 +1,24 @@ {% extends "base.html" %} -{% block htmltitle %} -{% if page.meta and page.meta.title %} -{{ page.meta.title }} | {{ config.site_name }} -{% elif page.title and not page.is_homepage %} -{{ page.title | striptags }} | {{ config.site_name }} -{% else %} -{{ config.site_name }} -{% endif %} +{% block title %} + {% if page.meta and page.meta.title %} + {{ page.meta.title }} - {{ config.site_name }} + {% else %} + {{ page.title | default(config.site_name, true) }} + {% endif %} {% endblock %} {% block extrahead %} - +{{ super() }} + {% endblock %}