Merge pull request #432 from jumpstarter-dev/backport-424-to-release-0.6

[Backport release-0.6] docs: improve reading flow

Author: mangelajo

CONTRIBUTING.md

@@ -1,258 +1,72 @@
 # Contributing
 
-Thank you for your interest in contributing to Jumpstarter! This document outlines the process for contributing to the project and provides guidelines to make the contribution process smooth.
+Thank you for your interest in contributing to Jumpstarter!
 
 ## Getting Help
 
-If you have questions or need help, here are the best ways to connect with the community:
-
-### Community Resources
-
-- **Matrix Chat**: Join our [Matrix community](https://matrix.to/#/#jumpstarter:matrix.org) for real-time discussions and support
-- **Weekly Meetings**: Participate in our [weekly community meetings](https://meet.google.com/gzd-hhbd-hpu) to discuss development and get help
-- **Etherpad**: Check our [Etherpad](https://etherpad.jumpstarter.dev/pad-lister) for meeting notes and collaborative documentation
-- **GitHub Issues**: [Open an issue](https://github.com/jumpstarter-dev/jumpstarter/issues) in the repository for bug reports and feature requests
-- **Documentation**: Visit our [documentation](https://jumpstarter.dev/) for comprehensive guides and tutorials
-
-## Code of Conduct
-
-Please be respectful and considerate of others when contributing to the project.
+- **Matrix Chat**: Join our [Matrix community](https://matrix.to/#/#jumpstarter:matrix.org)
+- **GitHub Issues**: [Open an issue](https://github.com/jumpstarter-dev/jumpstarter/issues)
+- **Documentation**: Visit our [documentation](https://jumpstarter.dev/)
+- **Weekly Meetings**: [Google Meet](https://meet.google.com/gzd-hhbd-hpu)
+- **Etherpad**: [Collaborative docs](https://etherpad.jumpstarter.dev/pad-lister)
 
 ## Getting Started
 
 1. Fork the repository
 2. Clone your fork locally
-3. Set up the development environment
-4. Make your changes on a new branch
+3. Set up the development environment: `make sync` and `make test`
+4. Make changes on a new branch
 5. Test your changes thoroughly
 6. Submit a pull request
 
-## Development Setup
-
-```shell
-# Install dependencies
-make sync
-
-# Run tests
-make test
-```
-
 ## Contribution Guidelines
 
 ### Making Changes
 
-- Keep changes focused and related to a single issue
-- Follow the existing code style and conventions
-- Add tests for new features or bug fixes
-- Update documentation as needed
+- Focus on a single issue
+- Follow existing code style
+- Add tests and update documentation
 
 ### Commit Messages
 
-- Use clear and descriptive commit messages
+- Use clear, descriptive messages
 - Reference issue numbers when applicable
 - Follow conventional commit format when possible
 
 ### Pull Requests
 
-- Provide a clear description of the changes
-- Link to any relevant issues
-- Ensure all tests pass before submitting
-- Be responsive to feedback and questions
+- Provide a clear description
+- Link to relevant issues
+- Ensure all tests pass
 
 ## Types of Contributions
 
 ### Code Contributions
-
-We welcome contributions to the core codebase, including bug fixes, features, and improvements.
+We welcome bug fixes, features, and improvements to the core codebase.
 
 ### Contributing Drivers
 
-If you are working on a driver or adapter library of general interest, please consider submitting it to this repository, as it will become available to all Jumpstarter users.
-
-To create a new driver scaffold, you can use the `create_driver.sh` script:
+To create a new driver scaffold:
 
 ```shell
-./__templates__/create_driver.sh vendor_name driver_name "Your Name" "your.email@example.com"
-```
-
-This will create the necessary files and structure for your driver in the `packages/` directory. For example:
-
-```shell
-./__templates__/create_driver.sh yepkit Ykush "Your Name" "your.email@example.com"
-```
-
-Creates:
-```
-packages/jumpstarter_driver_yepkit/jumpstarter_driver_yepkit/__init__.py
-packages/jumpstarter_driver_yepkit/jumpstarter_driver_yepkit/client.py
-packages/jumpstarter_driver_yepkit/jumpstarter_driver_yepkit/driver_test.py
-packages/jumpstarter_driver_yepkit/jumpstarter_driver_yepkit/driver.py
-packages/jumpstarter_driver_yepkit/.gitignore
-packages/jumpstarter_driver_yepkit/pyproject.toml
-packages/jumpstarter_driver_yepkit/README.md
-packages/jumpstarter_driver_yepkit/examples/exporter.yaml
+$ ./__templates__/create_driver.sh driver_package DriverClass "Your Name" "your.email@example.com"
 ```
 
-#### Driver Structure
-
-A Jumpstarter driver typically consists of:
-
-1. **Driver Implementation**: The core functionality that interfaces with the device or service
-2. **Client Implementation**: Client code to interact with the driver
-3. **Tests**: Tests to verify the driver's functionality
-4. **Examples**: Example configurations showing how to use the driver
-5. **Documentation**: Clear documentation on setup and usage
-
-#### Private Drivers
-
-If you are creating a driver or adapter library for a specific need, not of general interest, or that needs to be private, please consider forking our [jumpstarter-driver-template](https://github.com/jumpstarter-dev/jumpstarter-driver-template).
-
-#### Driver Development Workflow
-
-After creating your driver skeleton:
-
-1. Implement the driver functionality according to the Jumpstarter driver interface
-2. Write comprehensive tests for your driver
-3. Create example configurations
-4. Document the setup and usage in the README.md
-5. Submit a pull request to the main Jumpstarter repository
-
-#### Testing Your Driver
-
-To test your driver during development:
-
-```shell
-# From the project root
-make sync  # Synchronize dependencies
-cd packages/your_driver_package
-pytest     # Run tests for your driver
-```
-
-#### Driver Best Practices
-
-- Follow the existing code style and conventions
-- Write comprehensive documentation
-- Include thorough test coverage
-- Create example configurations for common use cases
-- Keep dependencies minimal and well-justified
-
-### Documentation Contributions
-
-We welcome improvements to our documentation.
-
-#### Documentation System Overview
+For private drivers, consider forking our [jumpstarter-driver-template](https://github.com/jumpstarter-dev/jumpstarter-driver-template).
 
-Jumpstarter uses [Sphinx](https://www.sphinx-doc.org/en/master/) with Markdown support for its documentation. The documentation is organized into various sections covering different aspects of the project.
+Test your driver: `make pkg-test-${package_name}`
 
-#### Setting Up Documentation Environment
+### Contributing Documentation
 
-To contribute to the documentation, you'll need to set up your development environment:
-
-1. Clone the Jumpstarter repository
-2. Navigate to the docs directory
-3. Install dependencies (if not already installed with the main project)
-
-#### Building the Documentation Locally
-
-To build and preview the documentation locally:
+Jumpstarter uses Sphinx with Markdown. Build and preview locally:
 
 ```shell
-cd docs
-make html      # Build HTML documentation
-make docs-serve # Serve documentation locally for preview
-```
-
-The documentation will be available at http://localhost:8000 in your web browser.
-
-#### Documentation Structure
-
-- `docs/source/`: Root directory for documentation source files
-  - `index.md`: Main landing page
-  - `*.md`: Various markdown files for documentation sections
-  - `_static/`: Static assets like images and CSS
-  - `_templates/`: Custom templates
-
-#### Writing Documentation
-
-Documentation is written in Markdown with some Sphinx-specific extensions. Common syntax includes:
-
-```markdown
-# Heading 1
-## Heading 2
-### Heading 3
-
-*italic text*
-**bold text**
-
-- Bullet list item
-- Another item
-
-1. Numbered list
-2. Second item
-
-[Link text](URL)
-
-![Image alt text](path/to/image.png)
-
-```{note}
-This is a note admonition
-```
-
-```{warning}
-This is a warning admonition
+$ make docs-serve
 ```
 
-```python
-# This is a code block
-def example():
-    print("Hello, world!")
-```
-```
-
-#### Documentation Style Guide
-
-Please follow these guidelines when writing documentation:
-
-1. Use clear, concise language
-2. Write in the present tense
-3. Use active voice when possible
-4. Include practical examples
-5. Break up text with headers, lists, and code blocks
-6. Target both beginners and advanced users with appropriate sections
-7. Provide cross-references to related documentation
-
-#### Adding New Documentation Pages
-
-To add a new documentation page:
-
-1. Create a new Markdown (`.md`) file in the appropriate directory
-2. Add the page to the relevant `index.md` or `toctree` directive
-3. Build the documentation to ensure it appears correctly
-
-#### Documentation Versioning
-
-Documentation is versioned alongside the main Jumpstarter releases. When making changes, consider whether they apply to the current version or future versions.
-
-#### Documentation Tips
-
-- **Screenshots**: Include screenshots for complex UI operations
-- **Command Examples**: Always include example commands with expected output
-- **Troubleshooting**: Add common issues and their solutions
-- **Links**: Link to relevant external resources when appropriate
-
-#### Submitting Documentation Changes
-
-Once your documentation changes are complete:
-
-1. Build the documentation to verify there are no errors
-2. Submit a pull request with your changes
-3. Respond to feedback during the review process
-
-### Example Contributions
-
-To add a new example:
+Documentation recommended practices:
 
-1. Create a new directory in the `examples/` folder with a descriptive name
-2. Include a comprehensive `README.md` with setup and usage instructions
-3. Follow the structure of existing examples
-4. Ensure the example is well-documented and easy to follow
+- Use clear, concise language
+- Include practical examples
+- Break up text with headers, lists, and code blocks
+- Target both beginners and advanced users

README.md

@@ -1,4 +1,4 @@
-# ![bolt](./assets/bolt.svg) Jumpstarter
+# ![bolt](assets/bolt.svg) Jumpstarter
 
 [![Matrix](https://img.shields.io/matrix/jumpstarter%3Amatrix.org?color=blue)](https://matrix.to/#/#jumpstarter:matrix.org)
 [![Etherpad](https://img.shields.io/badge/Etherpad-Notes-blue?logo=etherpad)](https://etherpad.jumpstarter.dev/pad-lister)
@@ -8,13 +8,12 @@ A free, open source tool for automated testing on real and virtual hardware with
 
 ## Highlights
 
-- 🚀 **Unified Testing** - One tool for local, virtual, and remote hardware
+- 🧪 **Unified Testing** - One tool for local, virtual, and remote hardware
 - 🐍 **Python-Powered** - Leverage Python's testing ecosystem
-- 🛠️ **Hardware Abstraction** - Simplify complex hardware interfaces with drivers
-- 🔌 Built-in support for common interfaces such as [CAN](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-can), [IP](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-network), [GPIO](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-raspberrypi), [U-Boot](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-uboot), [SD Wire](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-sdwire), etc.
-- 💻 **Collaborative** - Share test hardware globally
-- 🔄 **CI/CD Ready** - Works with cloud native developer environments and pipelines
-- 🖥️ **Cross-Platform** - Supports Linux and macOS
+- 🔌 **Hardware Abstraction** - Simplify complex hardware interfaces with drivers
+- 🌐 **Collaborative** - Share test hardware globally
+- ⚙️ **CI/CD Ready** - Works with cloud native developer environments and pipelines
+- 💻 **Cross-Platform** - Supports Linux and macOS
 
 ## Installation
 

__templates__/create_driver.sh

@@ -28,7 +28,7 @@ mkdir -p ${MODULE_DIRECTORY}
 mkdir -p ${DRIVER_DIRECTORY}/examples
 
 # Define paths
-DOCS_DIRECTORY=docs/source/api-reference/drivers
+DOCS_DIRECTORY=docs/source/reference/package-apis/drivers
 DOC_FILE=${DOCS_DIRECTORY}/${DRIVER_NAME}.md
 README_FILE=${DRIVER_DIRECTORY}/README.md