Documentation general improvements (#2291)

* Addition of examples for analyse logs command on advance reference section * Addition of autonomy develop and push-all command documentation * Addition of introduction pages for sections: - Advanced Reference > Commands - Configure Service - Get Started * Fix typos and some generic text improvements --------- Co-authored-by: Naiane B <[email protected]>
valory-xyz · Jan 13, 2025 · 530e7d5 · 530e7d5
1 parent aab6acb
commit 530e7d5
Show file tree

Hide file tree

Showing 12 changed files with 242 additions and 11 deletions.
diff --git a/docs/advanced_reference/commands/autonomy_analyse.md b/docs/advanced_reference/commands/autonomy_analyse.md
@@ -260,9 +260,44 @@ autonomy analyse logs [OPTIONS]
 :   Show the help message and exit.
 
 ### Examples
-!!! info
-    This section will be added soon.
 
+Analyze logs from the build directory `./abci_build_hAsH/persistent_data/logs` for 2 agents:
+
+```bash   
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' -a 'aea_1'
+```
+
+View logs for 2 agents between specific times:
+
+```bash   
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --start-time "2024-01-20 10:00:00,000" --end-time "2024-01-20 11:00:00,000"
+```
+
+View logs for period `2` and round `RegistrationRound`:
+
+```bash
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --period 2 --round RegistrationRound
+```
+
+View only the FSM state transitions:
+
+```bash   
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --fsm
+```
+
+Filter by log level `ERROR` and behaviour `RegistrationBehaviour`:
+
+```bash   
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' --log-level ERROR --behaviour RegistrationBehaviour
+```
+
+Use regex patterns to filter logs, include lines with `consensus` and exclude lines with `debug`
+
+```bash
+autonomy analyse logs --from-dir ./abci_build_hAsH/persistent_data/logs -a 'aea_0' -ir ".*consensus.*" -er ".*debug.*"
+```
+
+These examples demonstrate various ways to filter and analyze agent service logs. You can combine multiple options to narrow down the log output to exactly what you need for debugging or analysis.
 
 ## `autonomy analyse benchmarks`
 

diff --git a/docs/advanced_reference/commands/autonomy_deploy.md b/docs/advanced_reference/commands/autonomy_deploy.md
@@ -102,11 +102,14 @@ autonomy deploy build [OPTIONS] [KEYS_FILE]
 `--agent-memory-limit INTEGER`
 :   Set agent memory usage limit.
 
-`--remote``
-:   To use `a remote registry.
+`--number-of-services INTEGER`
+    Number of services (i.e., separate deployment folders) to build. Default is 1.
 
-`--local``
-:   To use `a local registry.
+`--remote`
+:   To use a remote registry.
+
+`--local`
+:   To use a local registry.
 
 `-p`
 :   Ask for password interactively.
@@ -123,6 +126,14 @@ autonomy deploy build keys.json -ltm
 
 Builds a service deployment using the keys stored in the file `keys.json` and applying environment variables to the service configuration file. The deployment will be generated by default for as many agents as keys are stored in `keys.json`. By default, the command searches for the file `keys.json`, if no file name is provided.
 
+You can build multiple service deployments at once using the `--number-of-services` parameter. Each service will be created in its own `abci_build_*` folder:
+
+```bash
+autonomy deploy build --number-of-services 2 keys.json
+```
+
+Note: Use `--n` to set the number of agents per service, and use `--number-of-services` to build multiple separate services at once.
+
 If you are manually defining `keys.json` make sure to include `ledger` property for a key object. This will be used when writing key files to the deployment environment. If you don't specify the property `ethereum` will be used as default ledger identifier, so if you're running an agent against a different ledger (eg. `solana`) you'll have to specify this property manually like this
 
 ```json

diff --git a/docs/advanced_reference/commands/autonomy_develop.md b/docs/advanced_reference/commands/autonomy_develop.md
@@ -0,0 +1,26 @@
+Development tools for agent services.
+
+## Usage
+```bash
+autonomy develop [OPTIONS] COMMAND [ARGS]...
+```
+
+## Options
+`--help`
+:   Show the help message and exit.
+
+## `autonomy develop service-registry-network`
+Run service registry contracts locally.
+
+### Usage
+```bash
+autonomy develop service-registry-network [OPTIONS]
+```
+
+### Examples
+
+Run service registry contracts locally
+
+```bash
+autonomy develop service-registry-network
+```
diff --git a/docs/advanced_reference/commands/autonomy_fetch.md b/docs/advanced_reference/commands/autonomy_fetch.md
@@ -1,4 +1,5 @@
 Fetch an agent or agent service from a registry using its public ID, hash, or token ID.
+The `autonomy fetch` command allows you to download service files from either a local or remote registry.
 
 ## Usage
 ```bash
@@ -95,7 +96,7 @@ Fetch the agent service `hello_world` from a local registry with an explicit pat
 autonomy --registry-path=./packages fetch valory/hello_world:0.1.0 --service --local
 ```
 
-Fetch the agent service `hello_world` from a remote registry ([IPFS](https://ipfs.io)):
+Fetch the agent service `hello_world` from a remote registry using [IPFS](https://ipfs.io) hash:
 ```bash
 autonomy fetch valory/hello_world:0.1.0:bafybeihl6j7ihkytk4t4ca2ffhctpzydwi6r4a354ubjasttuv2pw4oaci --service --remote
 ```
@@ -104,3 +105,22 @@ Fetch the agent service with the token ID `123` on Gnosis chain:
 ```bash
 autonomy fetch 123 --use-gnosis
 ```
+
+### Viewing Remote Registry Files
+
+Before fetching a service, you can inspect its contents in on IPFS through `https://gateway.autonolas.tech/ipfs/<hash>/`
+
+## Common Issues and Solutions
+
+### Service Not Found
+- Verify the service ID is correct
+- Check registry connection
+- Ensure you're using the correct registry flag (--local or --remote)
+
+### Missing Dependencies
+- Run `autonomy packages sync` to update local packages
+- Check service requirements in `service.yaml`
+
+### Permission Issues
+- Verify write permissions in packages directory
+- Run with appropriate permissions
diff --git a/docs/advanced_reference/commands/autonomy_push_all.md b/docs/advanced_reference/commands/autonomy_push_all.md
@@ -0,0 +1,21 @@
+
+Push all available packages to a registry.
+
+## Usage
+```bash
+autonomy push-all [OPTIONS]
+```
+
+## Options
+`--packages-dir PATH`
+:   Path to the packages directory.
+
+`--help`
+:   Show the help message and exit.
+
+## Examples
+Push all packages
+
+```bash
+autonomy push-all --packages-dir ./packages
+```
diff --git a/docs/advanced_reference/commands/autonomy_replay.md b/docs/advanced_reference/commands/autonomy_replay.md
@@ -44,4 +44,4 @@ Tendermint runner.
 
 ## Examples
 
-Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md).
+Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md).
diff --git a/docs/advanced_reference/commands/index.md b/docs/advanced_reference/commands/index.md
@@ -0,0 +1,62 @@
+# Open Autonomy CLI Overview
+
+This page provides a quick reference to commonly used CLI commands in the Open Autonomy framework. Each command has a brief description and basic usage example, with links to more detailed documentation.
+
+## Core Commands
+
+### autonomy analyse
+Analyse an agent service, including ABCI app specifications, docstrings, logs, and more.
+
+[Detailed analyse documentation](./advanced_reference/commands/autonomy_analyse.md)
+
+### autonomy deploy
+Deploy an agent service using various deployment backends (Docker, Kubernetes, or localhost).
+
+[Detailed deploy documentation](./advanced_reference/commands/autonomy_deploy.md)
+
+### autonomy develop
+Development tools for agent services.
+
+[Detailed develop documentation](./advanced_reference/commands/autonomy_develop.md)
+
+### autonomy fetch
+Fetch an agent or service from a registry.
+
+[Detailed fetch documentation](./advanced_reference/commands/autonomy_fetch.md)
+
+### autonomy mint
+Mint components and services on-chain.
+
+[Detailed mint documentation](./advanced_reference/commands/autonomy_mint.md)
+
+### autonomy push-all
+Push all available packages to a registry.
+
+[Detailed push-all documentation](./advanced_reference/commands/autonomy_push_all.md)
+
+### autonomy replay
+Replay tools for agent services.
+
+[Detailed replay documentation](./advanced_reference/commands/autonomy_replay.md)
+
+### autonomy service
+Manage on-chain services.
+
+[Detailed service documentation](./advanced_reference/commands/autonomy_service.md)
+
+## Additional Information
+
+- Most commands support the `--help` flag for detailed usage information
+- Commands that interact with blockchains typically require a key file
+- Many commands have additional options for customization and configuration
+- See the [detailed command reference](./advanced_reference/commands/autonomy_analyse.md) for complete documentation of each command
+
+## Common Options
+
+Many commands share common options:
+
+- `--registry`: Specify the registry to use (default: remote)
+- `--chain`: Select blockchain network (e.g., ethereum, polygon)
+- `--key`: Path to key file for blockchain transactions
+- `--password`: Password for encrypted key files
+- `--help`: Show help message and exit
diff --git a/docs/advanced_reference/index.md b/docs/advanced_reference/index.md
@@ -1,4 +1,5 @@
-#Advanced reference - index
+# Advanced reference
+
 In this section you will find advanced developer topics such as the API and CLI documentation,
 debugging tools and other topics relevant for the development of agent services with 
 the {{open_autonomy}} framework.
diff --git a/docs/configure_service/index.md b/docs/configure_service/index.md
@@ -0,0 +1,11 @@
+# Configure Service
+
+This section provides detailed information and guides for configuring an agent service. 
+Here you will find:
+
+- [The service configuration file](./service_configuration_file.md): Learn how to set up and customize your service's configuration
+- [Configure access to external chains](./configure_access_external_chains.md): Guide for configuring your service to work with different blockchain networks
+- [On-chain deployment checklist](./on-chain_deployment_checklist.md): Requirements and steps for deploying your service on-chain
+- [Analyze and test](./analyze_test.md): Tools and practices for testing and analyzing your service
+
+These guides will help you properly configure and validate your agent service for both development and production environments.
diff --git a/docs/get_started/index.md b/docs/get_started/index.md
@@ -0,0 +1,37 @@
+# Getting Started
+
+Welcome to the Open Autonomy Framework documentation! This section will help you understand and get started with building your own agent services.
+
+## What are Agent Services?
+
+Agent services are decentralized off-chain services that run as multi-agent systems and are secured on public blockchains. They enable complex processing and autonomous actions while maintaining decentralization, trust-minimization, transparency, and robustness.
+
+## Key Topics
+
+1. [What is an Agent Service?](./what_is_an_agent_service.md)  
+   Learn about the architecture and components of agent services, including how they work and interact with blockchain networks.
+
+2. [Why do we need Agent Services?](./why_do_we_need_agent_services.md)  
+   Understand the challenges in blockchain technology that agent services address and their role in the crypto ecosystem.
+
+3. [Use cases](./use_cases.md)  
+   Explore practical applications of agent services, from DAO operations to customizable infrastructure solutions.
+
+4. [Agent Services compared](./agent_services_compared_to.md)  
+   See how agent services compare to other software solutions and understand when to use them.
+
+## Next Steps
+
+After understanding the basics of agent services, you can:
+
+- Follow our [Quick Start Guide](../guides/quick_start.md) to build your first agent service
+- Learn about the [Development Process](../guides/overview_of_the_development_process.md)
+- Explore [Key Concepts](../key_concepts/index.md) in depth
+
+## Need Help?
+
+If you have questions or need assistance:
+
+- Check our [Questions and Answers](../questions-and-answers.md) section
+- Join our community on [Discord](https://discord.com/invite/z2PT65jKqQ)
+- Visit the [Autonolas website](https://www.autonolas.network/) for more resources
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -1,3 +1,5 @@
+# Guides
+
 In this section you will find a number of useful guides which will help you
 to understand [the overall development process](./overview_of_the_development_process.md)
 of an agent service with the {{open_autonomy}} framework, including:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -36,10 +36,11 @@ extra_css:
 nav:
   - Home: 'index.md'
   - Get started:
+    - 'get_started/index.md'
     - What is an agent service: 'get_started/what_is_an_agent_service.md'
     - Why do we need agent services: 'get_started/why_do_we_need_agent_services.md'
-    - Agent services compared to...: 'get_started/agent_services_compared_to.md'
     - Use cases: 'get_started/use_cases.md'
+    - Agent services compared: 'get_started/agent_services_compared_to.md'
   - Guides:
     - 'guides/index.md'
     - Set up: 'guides/set_up.md'
@@ -68,6 +69,7 @@ nav:
       - Sequence diagram: 'key_concepts/poc-diagram.md'
     - Threat model: 'key_concepts/threat_model.md'
   - Configure the service:
+    - 'configure_service/index.md'
     - The service configuration file: 'configure_service/service_configuration_file.md'
     - Configure access to external chains: 'configure_service/configure_access_external_chains.md'
     - On-chain deployment checklist: 'configure_service/on-chain_deployment_checklist.md'
@@ -76,14 +78,17 @@ nav:
     - 'advanced_reference/index.md'
     # - publish fetch: 'guides/publish_fetch_packages.md'
     - Commands:
+      - 'advanced_reference/commands/index.md'
       - autonomy deploy: 'advanced_reference/commands/autonomy_deploy.md'
       - autonomy build-image: 'advanced_reference/commands/autonomy_build-image.md'
       - autonomy replay: 'advanced_reference/commands/autonomy_replay.md'
       - autonomy analyse: 'advanced_reference/commands/autonomy_analyse.md'
       - autonomy fetch: 'advanced_reference/commands/autonomy_fetch.md'
       - autonomy scaffold: 'advanced_reference/commands/autonomy_scaffold.md'           
       - autonomy mint: 'advanced_reference/commands/autonomy_mint.md'           
-      - autonomy service: 'advanced_reference/commands/autonomy_service.md'           
+      - autonomy service: 'advanced_reference/commands/autonomy_service.md'
+      - autonomy develop: 'advanced_reference/commands/autonomy_develop.md'
+      - autonomy push-all: 'advanced_reference/commands/autonomy_push_all.md'
     - Developer tooling:
       - Dev mode: 'advanced_reference/developer_tooling/dev_mode.md'
       - Execution replay: 'advanced_reference/developer_tooling/execution_replay.md'
Original file line number	Diff line number	Diff line change
Expand Up		@@ -44,4 +44,4 @@ Tendermint runner.

		## Examples

		Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md).
		Find a complete example on how the [execution replay section](../developer_tooling/execution_replay.md).