How to link and explanation

[WolfgangFahl]

Technical Guide for NiceGUI Project Inclusion in the Solutions List

Objective

This guide outlines the steps required for your NiceGUI project's automatic inclusion in the NiceGUI solutions list, as detailed in the provided source code.

Automatic Inclusion Criteria

Your project's presence in http://ngdemo.bitplan.com/solutions is determined by specific metadata from your GitHub and PyPI repositories.

Projects from pypi
https://pypi.org/search/?q=nicegui&o=-created

Projects from github
https://api.github.com/search/repositories?q=nicegui

see

• NiceGUI Component Bazaar zauberzeug/nicegui#1618
• https://www.reddit.com/r/nicegui/comments/18ke09e/nicegui_solutions_bazaar_prototype/

GitHub Requirements

1. Topic Tagging: Add topics to your repository (e.g., **nicegui**, python). nicegui is a helpful topic to be included.
   • Guide: Classifying your repository with topics
2. Repository URL: Ensure your project's GitHub repository URL is included in the metadata.
3. Star Count: The number of stars can enhance the project's visibility, although it's not a strict requirement.

PyPI Requirements

1. Package Name: Your package name on PyPI should clearly represent your project.
2. Metadata: Accurately complete the pyproject.toml or setup.py with your project's metadata.
   • Guide: Packaging Python Projects
   • Example:

     [project]
     name = "ngwidgets"
     keywords = ["nicegui", "components", "ui"]
     description = "NiceGUI widgets and solution bazaar"

3. Project URLs: In your pyproject.toml or setup.py, include URLs for the source code (GitHub link), tracker (issue tracking), and documentation.
4. Description: Provide a detailed description on PyPI, which will be used as the project's summary.

Project Detail Attributes

If you have set up your project as described above, the solution list update will effectively retrieve and display your project. Important attributes include:

• Name
• GitHub URL
• PyPI URL
• Description (from both GitHub and PyPI)
• Number of GitHub Stars
• Project's author/maintainer
• Creation Date (GitHub)

Steps for Developers

1. Tag Your GitHub Repository: Apply relevant topics to your GitHub repository.
2. Update Metadata: Ensure your pyproject.toml or setup.py accurately reflects your project's details on PyPI.
3. Maintain Your Repository: Regularly update and maintain your GitHub repository and PyPI listing for continued visibility.

Candidate Projects

To explore existing candidate projects for NiceGUI or to gauge the landscape, you can use the following search queries:

• GitHub Search by Topic: NiceGUI Projects on GitHub
• PyPI Search: nicegui Projects on PyPI
• General GitHub Search: NiceGUI Repositories

Updating Project Information

Changes in your GitHub or PyPI metadata will be reflected in the NiceGUI solutions list during the next update cycle.

Further Information

For more discussions or questions about the inclusion process, refer to the initial discussion at NiceGUI GitHub Discussion #1618.

Components.yaml

see http://ngdemo.bitplan.com/components/WolfgangFahl_nicegui_widgets

and the declaration at
https://github.com/WolfgangFahl/nicegui_widgets/blob/main/.components.yaml

# Components of https://github.com/WolfgangFahl/nicegui_widgets
# to be shown in nicegui solution bazaar as per
# https://github.com/WolfgangFahl/nicegui_widgets/issues/52
# see http://ngdemo.bitplan.com/solutions
# WF 2023-12-16
components:
- name: color_schema.py
  source: /ngwidgets/color_schema.py
  issue: 15
  demo_url: http://ngdemo.bitplan.com/color_schema
  demo_image_url: https://github.com/WolfgangFahl/nicegui_widgets/assets/1336221/2bb926d4-da56-4201-a04c-af032d4de08e
  description: >
    ColorSchema enables NiceGUI color customization.
    Includes palettes from https://www.materialpalette.com: RED, PINK, PURPLE,
    DEEP PURPLE, ...
- name: dict_edit.py
  source: /ngwidgets/dict_edit.py
  issue: 47
  demo_url: http://ngdemo.bitplan.com/dictedit
  demo_image_url: https://github.com/WolfgangFahl/nicegui_widgets/assets/1336221/405053ea-0b2e-42cf-b637-191e9541603d
  description: >
    DictEdit is a UI component for editing dictionaries
    or dataclasses, supporting dynamic fields with
    customizable options and validations.

Explanation of Fields in components.yaml

The components.yaml file serves as a catalog of components within a project. Each entry in this file describes a specific component with the following fields:

• name:

  • Description: The name of the component file, typically a Python script.
  • Example: In name: dict_edit.py, dict_edit.py is the Python script containing the component's code.

• description:

  • Description: A potentially multiline description of the component
  • Example: DictEdit is a UI component for editing dictionaries or dataclasses, supporting dynamic fields with customizable options and validations.

• source:

  • Description: The relative path to the component's source file within the project repository.
  • Example: /ngwidgets/dict_edit.py points to the location of dict_edit.py within the repository.

• issue:

  • Description: A reference to the issue number in the project's issue tracker that relates to this component.
  • Example: issue: 47 refers to issue number 47 in the project's GitHub issue tracker.

• demo_url:

  • Description: A URL pointing to a live demo of the component.
  • Example: http://ngdemo.bitplan.com/dictedit provides a link to interact with the dict_edit.py component.

• demo_image_url:

  • Description: A URL to an image showcasing the component. This helps users get a visual understanding of what the component looks like or how it functions.
  • Example: https://github.com/WolfgangFahl/nicegui_widgets/assets/1336221/d1682fce-975a-4ecc-a82e-c2c397e8222a is a link to an image of the dict_edit.py component.

This structure allows for a comprehensive and accessible overview of each component within the project, aiding users in understanding and utilizing the components effectively.

[WolfgangFahl]

A link to this howto should show up in the solutions list display