README
¶
Help Module
This repository contains the help module, which was formerly part of the Snider/Core framework. This module provides assistance and documentation functionality.
Getting Started
This project uses mkdocs-material to build the documentation. To get started, you will need to have Python and pip installed.
-
Install the dependencies:
pip install -r requirements.txt -
Run the development server:
mkdocs serve
Usage
To use the help module, you first need to import it in your Go project:
import "github.com/Snider/help"
Next, initialize the help service by calling the New function. The New function accepts an Options struct, which allows you to configure the documentation source.
Using a custom embed.FS
You can provide your own embed.FS as a documentation source. This is useful when you want to bundle the documentation with your application.
import (
"embed"
"github.com/Snider/help"
)
//go:embed all:my-docs/build
var myDocs embed.FS
func main() {
helpService, err := help.New(help.Options{
Assets: myDocs,
})
if err != nil {
// Handle error
}
// ...
}
Custom Static Site Source
You can also provide a custom directory containing a static website as the documentation source. To do this, set the Source field in the Options struct to the path of your static site directory:
helpService, err := help.New(help.Options{
Source: "path/to/your/static/site",
})
if err != nil {
// Handle error
}
Once the help service is initialized, you can use the Show() and ShowAt() methods to display the documentation.
Displaying Help
The Show() method opens the help window to the main page.
err := helpService.Show()
if err != nil {
// Handle error
}
The ShowAt() method opens the help window to a specific anchor. The provided anchor is normalized into a URL. For example, calling ShowAt("ui/how/settings#resetPassword") will open the help window to a URL similar to http://localhost:8080/docs/ui/how/settings/index.html#resetPassword. The exact URL depends on how your display service resolves these paths.
err := helpService.ShowAt("ui/how/settings#resetPassword")
if err != nil {
// Handle error
}
Documentation
¶
Overview ¶
without a `Snider/display` module. When a display module is not available, the service falls back to a direct `wails3` implementation for displaying the help window, ensuring that the help functionality remains available in different system configurations.
The package defines several interfaces (`Logger`, `App`, `Core`, `Display`, `Help`) to decouple the help service from the main application, promoting a clean architecture and making it easier to mock dependencies for testing.
Usage: To use the help service, create a new instance with `New()`, providing `Options` to configure the source of the help assets. The service can then be initialized with a `Core` and `Display` implementation. The `Show()` and `ShowAt()` methods can be called to display the help window or a specific section of it.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App interface {
// Logger returns the application's logger instance.
Logger() Logger
}
App defines the interface for accessing application-level components, such as the logger. This allows the help service to interact with the application's infrastructure in a loosely coupled manner.
type Core ¶
type Core interface {
// ACTION dispatches a message to the core runtime for processing.
// This is used to trigger actions like opening a window.
ACTION(msg map[string]any) error
// App returns the application-level context.
App() App
}
Core defines the interface for the core runtime functionalities that the help service depends on. This typically includes methods for performing actions and accessing the application context.
type Display ¶
type Display interface{}
Display defines the interface for a display service. The help service uses this interface to check for the presence of a display module, allowing it to function as an optional dependency.
type Help ¶
type Help interface {
// Show displays the main help window.
Show() error
// ShowAt displays a specific section of the help documentation,
// identified by an anchor.
ShowAt(anchor string) error
// ServiceStartup is a lifecycle method called when the application starts.
ServiceStartup(ctx context.Context) error
}
Help defines the public interface of the help service. It exposes methods for showing the help window and navigating to specific sections.
type Logger ¶
type Logger interface {
// Info logs an informational message.
Info(message string, args ...any)
// Error logs an error message.
Error(message string, args ...any)
}
Logger defines the interface for a basic logger. It includes methods for logging informational and error messages, which helps in decoupling the help service from a specific logging implementation.
type Options ¶
type Options struct {
// Source specifies the directory or path to the help content.
// If empty, it defaults to "mkdocs".
Source string
// Assets provides an alternative way to specify the help content
// using a filesystem interface, which is useful for embedded assets.
Assets fs.FS
}
Options holds the configuration for the help service. It allows for customization of the help content source.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service manages the in-app help system. It handles the initialization of the help content, interaction with the core runtime, and display of the help window.
func New ¶
New creates a new instance of the help Service. It initializes the service with the provided options, setting up the asset filesystem based on the specified source. If no source is provided, it defaults to the embedded "mkdocs" content.
Example:
// Create a new help service with default options.
helpService, err := help.New(help.Options{})
if err != nil {
log.Fatal(err)
}
Example ¶
// Create a new help service with default options.
// This demonstrates the simplest way to create a new service.
// The service will use the default embedded "mkdocs" content.
s, err := New(Options{})
if err != nil {
fmt.Printf("Error creating new service: %v", err)
return
}
if s != nil {
fmt.Println("Help service created successfully.")
}
Output: Help service created successfully.
func (*Service) Init ¶
Init initializes the service with its core dependencies. This method is intended to be called by the dependency injection system of the application to provide the necessary `Core` and `Display` implementations.
func (*Service) ServiceStartup ¶
ServiceStartup is a lifecycle method that is called by the application when it starts. It performs necessary checks to ensure that the service has been properly initialized with its dependencies.
func (*Service) Show ¶
Show displays the main help window. If a `Display` service is available, it sends an action to the core runtime to open the window. Otherwise, it falls back to using the `wails3` application instance to create a new window. This ensures that the help functionality is available even when the `Snider/display` module is not in use.
Example ¶
// Create a new service and initialize it with mock dependencies.
s, _ := New(Options{})
s.Init(&MockCore{}, &MockDisplay{})
// Call the Show method. In a real application, this would open a help window.
// Since we are using a mock core, it will just record the action.
if err := s.Show(); err != nil {
fmt.Printf("Error showing help: %v", err)
} else {
fmt.Println("Show method called.")
}
Output: Show method called.
func (*Service) ShowAt ¶
ShowAt displays a specific section of the help documentation, identified by an anchor. Similar to `Show`, it uses the `Display` service if available, or falls back to a direct `wails3` implementation. The anchor is appended to the URL, allowing the help window to open directly to the relevant section.
Example ¶
// Create a new service and initialize it with mock dependencies.
s, _ := New(Options{})
s.Init(&MockCore{}, &MockDisplay{})
// Call the ShowAt method. In a real application, this would open a help
// window at a specific anchor.
if err := s.ShowAt("getting-started"); err != nil {
fmt.Printf("Error showing help at anchor: %v", err)
} else {
fmt.Println("ShowAt method called for 'getting-started'.")
}
Output: ShowAt method called for 'getting-started'.
Source Files
Directories