docs: improved getting started, tool docs, and docstrings

docs/automation.rst

@@ -8,12 +8,11 @@ We will be using shell scripts, cron jobs, and other tools to automate the workf
 
 .. note::
 
-   This is a work in progress. We intend to make gptme more powerful for automations, see `issue #1 <https://github.com/ErikBjare/gptme/issues/143>`_ for more details on this plan.
+   This is a work in progress. We intend to make gptme more powerful for automations, see `issue #143 <https://github.com/ErikBjare/gptme/issues/143>`_ for more details on this plan.
 
 
 
-Example: Implement feature
---------------------------
+.. rubric:: Example: Implement feature
 
 This example demonstrates how to implement a feature in a codebase using gptme, making sure the code is correct before creating a pull request.
 

docs/automation/example_activity_summary.rst

@@ -1,5 +1,4 @@
-Example: Daily Activity Summary
--------------------------------
+.. rubric:: Example: Daily Activity Summary
 
 Here's an example of how to use gptme to generate a daily summary based on ActivityWatch data using a shell script:
 

docs/automation/example_code_review.rst

@@ -1,5 +1,4 @@
-Example: Automated Code Review
-------------------------------
+.. rubric:: Example: Automated Code Review
 
 This example demonstrates a simple and composable approach to automated code review using gptme and shell scripting.
 
@@ -8,7 +7,6 @@ This example demonstrates a simple and composable approach to automated code rev
    .. code-block:: bash
 
       #!/bin/bash
-
       # Usage: ./review_pr.sh <repo> <pr_number>
 
       repo=$1

docs/conf.py

@@ -4,7 +4,6 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 import re
 from datetime import date
 
@@ -91,6 +90,7 @@ def setup(app):
     "sphinx.ext.autosectionlabel",
     "sphinx_click",
     "sphinxcontrib.programoutput",
+    "sphinxcontrib.asciinema",
 ]
 
 
@@ -116,6 +116,7 @@ def setup(app):
     ("py:class", "pathlib.Path"),
     ("py:class", "flask.app.Flask"),
     ("py:class", "gptme.tools.python.T"),
+    ("py:class", "threading.Thread"),
 ]
 
 # -- Options for HTML output -------------------------------------------------

docs/demos.rst

@@ -10,80 +10,64 @@ Demos
    :local:
    :backlinks: none
 
-Snake with curses
------------------
 
-Generate a snake game that runs in the terminal using curses, and then modify it to add color.
-
-.. raw:: html
+.. rubric:: Snake with curses
 
-   <a href="https://asciinema.org/a/621992">
-   <img src="https://github.com/ErikBjare/gptme/assets/1405370/72ac819c-b633-495e-b20e-2e40753ec376" width="600" />
-   </a>
+Generate a snake game that runs in the terminal using curses, and then modify it to add color.
 
+.. asciinema:: 621992
+   :autoplay: true
 
 Steps
 
-- Create a snake game with curses to snake.py
-- Running fails, ask gptme to fix a bug
-- Game runs
-- Ask gptme to add color
-- Minor struggles
-- Finished game with green snake and red apple pie!
+#. Create a snake game with curses to snake.py
+#. Running fails, ask gptme to fix a bug
+#. Game runs
+#. Ask gptme to add color
+#. Minor struggles
+#. Finished game with green snake and red apple pie!
 
-Mandelbrot with curses
-----------------------
+.. rubric:: Mandelbrot with curses
 
 Generate a program that renders mandelbrot with curses, and then modify it to add color.
 
-.. raw:: html
-
-    <a href="https://asciinema.org/a/621991">
-    <img src="https://github.com/ErikBjare/gptme/assets/1405370/570860ac-80bd-4b21-b8d1-da187d7c1a95" width="600" />
-    </a>
+.. asciinema:: 621991
+   :autoplay: true
 
 Steps
 
-- Render mandelbrot with curses to mandelbrot_curses.py
-- Program runs
-- Add color
+#. Render mandelbrot with curses to mandelbrot_curses.py
+#. Program runs
+#. Add color
 
 
-Fibonacci (old)
----------------
+.. rubric:: Fibonacci
 
 An old demo showing off basic code execution and shell interaction.
 
-.. raw:: html
-
-   <a href="https://asciinema.org/a/606375">
-   <img src="https://github.com/ErikBjare/gptme/assets/1405370/5dda4240-bb7d-4cfa-8dd1-cd1218ccf571" width="600" />
-   </a>
+.. asciinema:: 606375
+   :autoplay: true
 
 Steps
 
-- Create a new dir 'gptme-test-fib' and git init
-- Write a fib function to fib.py, commit
-- Create a public repo and push to GitHub
+#. Create a new dir 'gptme-test-fib' and git init
+#. Write a fib function to fib.py, commit
+#. Create a public repo and push to GitHub
 
-Answer question from URL
-------------------------
 
-Showing off basic URL loading from the prompt, and answering questions based on the content.
+.. rubric:: Answer question from URL
 
-.. raw:: html
+Showing off basic URL loading from the prompt, and answering questions based on the content.
 
-    <a href="https://asciinema.org/a/621997">
-    <img src="https://github.com/ErikBjare/gptme/assets/1405370/bae45488-f4ed-409c-a656-0c5218877de2" />
-    </a>
+.. asciinema:: 621997
+   :autoplay: true
 
 Steps
 
-- Ask who the CEO of Superuser Labs is, passing website URL
-- gptme browses the website, and answers correctly
+#. Ask who the CEO of Superuser Labs is, passing website URL
+#. gptme browses the website, and answers correctly
 
 
-Edit history with /edit
------------------------
+.. rubric:: Edit history with /edit
 
 TODO

docs/examples.rst

@@ -5,7 +5,6 @@ A list of things you can do with gptme.
 
 To see example output without running the commands yourself, check out the :doc:`demos`.
 
-
 .. code-block:: bash
 
     gptme 'write a web app to particles.html which shows off an impressive and colorful particle effect using three.js'
@@ -25,19 +24,28 @@ To see example output without running the commands yourself, check out the :doc:
     # it can read files using tools, if contents not provided in prompt
     gptme 'suggest improvements to my vimrc'
 
-
 Do you have a cool example? Share it with us in the `Discussions <https://github.com/ErikBjare/gptme/discussions>`_!
 
 
-Commit Message Generator
-------------------------
+.. rubric:: Skip confirmation and run in non-interactive mode
+
+You can skip confirmation prompts and run in non-interactive mode to terminate when all prompts have been completed.
+
+This should make it first write snake.py, then make the change in a following prompt:
+
+.. code-block:: bash
+
+    gptme --non-interactive --no-confirm 'create a snake game using curses in snake.py, dont run it' '-' 'make the snake green and the apple red'
+
+The '-' is special "multiprompt" syntax that tells the assistant to wait for the assistant to finish work on the next prompt (run until no more tool calls) before continuing. For more such non-interactive examples, see :doc:`automation`.
+
+
+.. rubric:: Generate Commit Messages
 
 Generate meaningful commit messages based on your git diff:
 
 .. code-block:: bash
 
-   #!/bin/bash
-   # Usage: git-commit-auto
    msg_file=$(mktemp)
    git diff --cached | gptme --non-interactive "Write a concise, meaningful commit message for this diff to `$msg_file`.
 
@@ -46,18 +54,14 @@ Generate meaningful commit messages based on your git diff:
 
    git commit -F "$msg_file"
 
-Generate Documentation
-----------------------
 
-Generate docstrings for all functions in a file:
+.. rubric:: Generate Documentation
 
-.. TODO: not automation, move to examples.
+Generate docstrings for all functions in a file:
 
 .. code-block:: bash
 
-   #!/bin/bash
    gptme --non-interactive "Patch these files to include concise docstrings for all functions, skip functions that already have docstrings. Include: brief description, parameters." $@
 
-
 These examples demonstrate how gptme can be used to create simple yet powerful automation tools. Each script can be easily customized and expanded to fit specific project needs.
 

docs/getting-started.rst

@@ -29,8 +29,7 @@ To initiate a new chat or select an existing one, execute:
 
 This will show you a list of past chats, allowing you to select one or start a new one.
 
-Writing a file
-**************
+.. rubric:: Writing a file
 
 You can then interact with the assistant. Lets start by asking it to write code.
 
@@ -50,8 +49,7 @@ You can then interact with the assistant. Lets start by asking it to write code.
 
 The assistant will prompt for your confirmation and save the file, as requested.
 
-Making changes
-**************
+.. rubric:: Making changes
 
 We can also start chats and request changes directly from the command line. The contents of any mentioned text files will be included as context, and the assistant will generate patches to apply the requested changes:
 
@@ -74,42 +72,23 @@ We can also start chats and request changes directly from the command line. The
    System: Patch applied
 
 .. note::
-    With the browser extras installed, the assistant can also process URLs included in the prompt.
+    With the :ref:`tools:browser` extras installed, the assistant can also process URLs included in the prompt.
 
-Other tools
-***********
+More tools
+**********
 
-You can read about other tools on the :doc:`tools` page.
+You can read about all the other tools on the :doc:`tools` page.
 
-Other interfaces
-****************
+Including :ref:`tools:shell`, :ref:`tools:python`, how to set up :ref:`tools:browser`, and use :ref:`tools:vision`.
 
-There are other ways to interact with the assistant:
+Interfaces
+**********
 
-Command line
-^^^^^^^^^^^^
+There are several ways to interact with gptme:
 
-Commands can also be executed directly from the command line. For example, one can skip confirmation prompts and  run in non-interactive mode to terminate when all prompts have been completed:
-
-.. code-block:: bash
-
-    gptme --non-interactive --no-confirm 'create a snake game using curses in snake.py, dont run it' '-' 'make the snake green and the apple red'
-
-This should make it first write snake.py, then make the change in a following prompt. The '-' is special "multiprompt" syntax that tells the assistant to wait for the next prompt before continuing.
-
-Web UI
-^^^^^^
-
-To run the assistant in a web interface, execute:
-
-.. code-block:: bash
-
-    gptme-server
-
-This should let you view your chats in a web browser and make basic requests.
-
-.. note::
-    The web interface is still in development and is not fully functional (no confirmation prompts or streaming).
+- :doc:`CLI <cli>`
+- :ref:`server:web ui`
+- :doc:`bot`
 
 Support
 -------

docs/server.rst

@@ -3,7 +3,7 @@ Server
 
 .. note::
    The server and web UI is still in development and does not have all the features of the CLI.
-   It does not support streaming, doesn't ask for confirmation before executing, lacks the ability to interrupt generations, etc.
+   It does not support streaming, doesn't ask for confirmation before executing, lacks the ability to interrupt responses and tool calls, etc.
 
 gptme has a minimal REST API with very minimalistic web UI.
 
@@ -16,6 +16,12 @@ It can be started by running the following command:
 Web UI
 ------
 
+.. code-block:: bash
+
+    gptme-server
+
+This should let you view your chats in a web browser and make basic requests.
+
 You can then access the web UI by visiting http://localhost:5000 in your browser.
 
-For more usage, see `the CLI documentation <cli.html#gptme-server>`_.
+For more usage, see :ref:`the CLI documentation <cli:gptme-server>`.