Docstrings generation

Index

Warning

In the examples in the documentation below, the methods are not prefixed by the module name even if they are private.

julia> using CTBase
julia> x = 1
julia> private_fun(x) # throw an error

must be replaced by

julia> using CTBase
julia> x = 1
julia> CTBase.private_fun(x)

However, if the method is reexported by another package, then, there is no need of prefixing.

julia> module OptimalControl
           import CTBase: private_fun
           export private_fun
       end
julia> using OptimalControl
julia> x = 1
julia> private_fun(x)

Documentation

CTBase.doc_app — Method

doc_app(_::CTBase.DocstringsAppTag)

Launches the Julia Docstrings Generator web app on localhost.

Starts an HTTP server on port 8080 and prints the local URL for access.

Arguments

::CTBase.DocstringsAppTag: A dispatch tag used to identify this application.

Returns

nothing: This function runs the server and does not return a result.

Example

julia> CTBase.doc_app(CTBase.DocstringsAppTag())
Open http://localhost:8080 in your browser.

source

CTBaseDocstrings.handled_doc_app — Method

handled_doc_app(req) -> HTTP.Messages.Response

Handles HTTP requests to serve the web app interface, process user-submitted code, and shut down the server.

Arguments

req: An HTTP request object representing an incoming request to the server.

Returns

response::HTTP.Response: An appropriate HTTP response depending on the request path and method.

Example

julia> using HTTP
julia> req = HTTP.Request("GET", "/");
julia> resp = handled_doc_app(req)
HTTP.Response(200 OK)

source

CTBaseDocstrings.html_code_doc_app — Method

html_code_doc_app() -> String

Returns the HTML string for the Julia Docstrings Prompt Generator web app.

This HTML includes the structure, layout, and style definitions required for a client-side interface with dark/light mode support, tabs for input areas, and interactive elements.

Returns

html::String: A complete HTML string to be served as the main page of the application.

Example

julia> html = html_code_doc_app();
julia> occursin("DOCTYPE html", html)
true

source

CTBase.docstrings — Method

docstrings(
    path::String;
    tests,
    context,
    apikey
) -> Tuple{Vector{Any}, String}

Sends code and optional context to the Mistral API and extracts generated docstrings.

Arguments

path::String: Path to the Julia source file.
tests: Optional path to a test file (default nothing).
context: Optional path to a context file for better generation (default nothing).
apikey::String: Mistral API key (default empty).

Returns

(pairs, response)::Tuple{Vector{Tuple{String, String}}, String}: A tuple containing extracted docstring-code pairs and a reconstructed version of the code with inserted docstrings.

Example

julia> CTBase.docstrings("example.jl", apikey="sk-...")
([("Docstring", "function f(x) ... end")], "...full reconstructed text...")

source

CTBaseDocstrings.code_unchanged_check — Method

code_unchanged_check(
    pairs,
    original_code::String;
    display
) -> Int64

Checks whether the generated docstring/code blocks altered the original code.

Arguments

pairs: A vector of (docstring, code) pairs.
original_code::String: The original source code as a string.
display::Bool: Whether to display line-by-line differences if any (default true).

Returns

code_changed::Int: Returns 1 if the code was changed, 0 otherwise.

Example

julia> code_unchanged_check([("doc", "function f() end")], "function f() end")
0

source

CTBaseDocstrings.docstrings_file — Method

docstrings_file(path; tests, context, apikey) -> String

Generates a new file with inserted docstrings and saves it to disk.

Arguments

path: Path to the source Julia file.
tests: Optional path to test file (default nothing).
context: Optional path to context file (default nothing).
apikey: API key for Mistral (default empty string).

Returns

outpath::String: Path to the new file with _docstrings appended to the original filename.

Example

julia> docstrings_file("myfile.jl", apikey="sk-...")
"myfile_docstrings.jl"

source

CTBaseDocstrings.extract_docstring_code_pairs — Method

extract_docstring_code_pairs(
    ai_text::String
) -> Tuple{Vector{Any}, String}

Extracts pairs of docstrings and code blocks from the given AI-generated text.

Arguments

ai_text::String: The full string response from the AI, possibly containing multiple docstring-code pairs.

Returns

(pairs, reponse)::Tuple{Vector{Tuple{String,String}}, String}: A tuple containing a vector of (docstring, code) pairs and a string reconstruction with triple-quoted docstrings prepended.

Example

julia> text = """"Docstring"""
function f(x)
  x + 1
end
";
julia> extract_docstring_code_pairs(text)
(("Docstring", "function f(x)
  x + 1
end"), ...)

source

CTBase.generate_prompt — Method

generate_prompt(
    code_text::String,
    tests_text::String,
    context_text::String
) -> String

Generates a well-structured and precise prompt to produce Julia docstrings in the Documenter.jl style, using provided code, tests, and context.

Arguments

code_text::String: The Julia code (structs and functions) to document.
tests_text::String: Optional related tests for improving examples.
context_text::String: Additional domain knowledge or technical explanation to improve doc quality.

Returns

prompt::String: A clear prompt ready for use with a language model like ChatGPT or Mistral.

Example

julia> code = "function square(x); x^2; end"
julia> CTBase.generate_prompt(code, "", "")
"Your task is to write docstrings for the following Julia code..."

source