Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/karimaziev/gpt-doc

Document Elisp code with chat GPT.
https://github.com/karimaziev/gpt-doc

chatgpt documentation documentation-tool elisp emacs gpt

Last synced: 4 days ago
JSON representation

Document Elisp code with chat GPT.

Awesome Lists containing this project

README 

        
#+OPTIONS: ^:nil tags:nil



* About



=gpt-doc= is an Emacs library designed to automate the documentation of Elisp code by leveraging the capabilities of the GPT API. It offers a seamless interface for sending Elisp code snippets to an intelligent documentation generation service and then, upon receiving the AI-generated documentation, inserts it precisely at the appropriate location in your Emacs buffer.



[[./gpt-doc.gif][./gpt-doc.gif]]



* Table of Contents                                       :TOC_2_gh:QUOTE:

#+BEGIN_QUOTE

- [[#about][About]]

- [[#requirements][Requirements]]

- [[#installation][Installation]]

  - [[#with-use-package-and-straightel][With use-package and straight.el]]

  - [[#manual-installation][Manual installation]]

- [[#setup-api-key][Setup API key]]

  - [[#as-a-string][As a string:]]

  - [[#as-a-predefined-authsource-function][As a predefined authsource function:]]

  - [[#as-a-custom-function][As a custom function]]

- [[#usage][Usage]]

  - [[#documentation-generation-process][Documentation Generation Process]]

  - [[#single-commands][Single commands]]

  - [[#batch-commands][Batch commands]]

- [[#customization][Customization]]

#+END_QUOTE



* Requirements



| Name           | Version |

|----------------+---------|

| Emacs          |    27.1 |

| [[https://platform.openai.com/account/api-keys][OpenAI API Key]] |         |



* Installation



To use =gpt-doc.el=, make sure you have Emacs version 27.1 or later installed.



** With use-package and straight.el

#+begin_src elisp :eval no

(use-package gpt-doc

  :straight (gpt-doc

             :repo "KarimAziev/gpt-doc"

             :type git

             :host github)

  :commands (gpt-doc))

#+end_src



** Manual installation



Download the source code and put it wherever you like, e.g. into =~/.emacs.d/gpt-doc/=



#+begin_src shell :eval no

git clone https://github.com/KarimAziev/gpt-doc.git ~/.emacs.d/gpt-doc/

#+end_src



Add the downloaded directory to the load path:



#+begin_src elisp :eval no

(add-to-list 'load-path "~/.emacs.d/gpt-doc/")

(require 'gpt-doc)

#+end_src



* Setup API key



Make sure that you have an [[https://platform.openai.com/account/api-keys][OpenAI API key]] before using the library. You can either set it as a string directly or define a function that returns the API key.



** As a string:

#+begin_src emacs-lisp

(setq gpt-doc-api-key "YOUR_API_KEY_TOKEN")

#+end_src



** As a predefined authsource function:

Add the following entry to your authentication sources file, which is typically located at =~/.authinfo.gpg= or =~/.authinfo=.

#+begin_example

machine api.openai.com login apikey password YOUR_API_KEY_TOKEN

#+end_example

And assign ~gpt-doc-api-key-from-auth-source~ to ~gpt-doc-api-key~:



#+begin_src emacs-lisp

(setq gpt-doc-api-key #'gpt-doc-api-key-from-auth-source)

#+end_src



** As a custom function



This function should return the API key.



 #+begin_src emacs-lisp

(defun my-gpt-get-api-key ()

  "Return api key for gpt."

  (let ((api-key "YOUR_API_KEY_TOKEN"))

    api-key))



(setq gpt-doc-api-key #'my-gpt-get-api-key)

#+end_src



* Usage



** Documentation Generation Process



#+begin_quote

[!NOTE]



When documenting a thing (function, variable, etc.), =gpt-doc= makes two separate requests to the GPT API to ensure high-quality and focused documentation:



- *Summary Sentence*: The first request generates a summary sentence that concisely describes the functionality.

- *Arguments Description*: The second request provides documentation for each argument, detailing their purposes and usage.



This two-request approach allows the GPT model to provide context-specific responses, resulting in accurate and well-formatted documentation.



Active streaming requests can be managed using the command =gpt-doc-abort-all=, which terminates any ongoing documentation requests.

#+end_quote



** Single commands



Run at the beginning or inside the function to generate and insert documentation:



- =M-x gpt-doc=



You can control the inclusion of related definitions for contextual richness with an optional prefix argument that influences the GPT system prompt:



  - With no prefix argument, the default behavior, as specified by =gpt-doc-default-context-strategy=, is used.

  - A prefix argument of 1 includes no related definitions.

  - A prefix argument of 4 includes shallow related definitions, such as directly used definitions within the thing being documented.

  - A prefix argument of 16 includes all related definitions, providing the most comprehensive context by expanding the documentation to include nested related definitions.



  If custom variable =gpt-doc-use-stream= is non-nil, generate and insert the documentation piece by piece as it is available, otherwise perform a synchronous request. Active streaming requests can be aborted with the command =gpt-doc-abort-all=.



- =M-x gpt-doc-with-context= Works the same as =gpt-doc=, but by default, it includes shallow related definitions.



- =M-x gpt-doc-with-full-context= Works the same as =gpt-doc=, but by default, it includes all related definitions.



** Batch commands



These commands operate on multiple definitions in the current buffer. The context inclusion for batch commands follows the same logic as the single commands, augmenting the GPT system prompt with relevant definitions as per the specified prefix argument. They can be called with a prefix argument, which has the same meaning as in =gpt-doc=.



Regardless of the value of =gpt-doc-use-stream=, they will stream the response (i.e., insert the documentation piece by piece as it becomes available).



Active streaming requests can be aborted with the command =gpt-doc-abort-all=.



- =M-x gpt-doc-regenerate-dups=

    Regenerate documentation for definitions with duplicate documentation strings.



- =M-x gpt-doc-document-all-undocumented=

    Generate documentation for all undocumented definitions in the buffer.



- =M-x gpt-doc-redocument-all=

    Regenerate documentation for all definitions backward starting from the current one. If there is no suitable definition at the point, start from the last one in the buffer.



* Customization

**** ~gpt-doc-gpt-model~

You can set the OpenAI API model with =gpt-doc-gpt-model=. The default model is =gpt-4-1106-preview=.



#+begin_src elisp

(setq gpt-doc-gpt-model "gpt-4")

#+end_src

**** ~gpt-doc-gpt-url~



You can specify the OpenAI API endpoint with =gpt-doc-gpt-url=. The default endpoint is "https://api.openai.com/v1/chat/completions".



#+begin_src elisp

(setq gpt-doc-gpt-url "https://api.openai.com/v1/chat/completions")

#+end_src

**** ~gpt-doc-gpt-temperature~

The temperature for the OpenAI GPT model used. Lower values make the responses more deterministic, and higher values make them more random. The default value is 0.1.

#+begin_src elisp

(setq gpt-doc-gpt-temperature 0.1)

#+end_src

**** ~gpt-doc-api-key~

An OpenAI =API= key (string). Can also be a function of no arguments that returns an =API= key (more secure).

Temperature

**** ~gpt-doc-use-stream~

Whether to use streaming.

**** ~gpt-doc-first-sentence-doc-prompt~

System prompt to generate first sentence of function documentation.

**** ~gpt-doc-args-prompt~

System prompt for ChatGPT to document Elisp arguments.

**** ~gpt-doc-variable-prompt~

System prompt (directive) for ChatGPT to document Elisp variables.

**** ~gpt-doc-docstring-positions~

An alist that maps definition types to their respective documentation positions. If the value of cell is a number, move forward across n balanced expressions. If the value is a function, it will be called with definition sexp and should return number to move forward across.

**** ~gpt-doc-prompt-types~

An alist that maps definition types to their respective documentation labels