Fix all Documenter warnings

Namely by adding docstrings for all the internal methods that were missing
them. Also used updated the docs CI to use the latest stable release (so we can
use `[sources]`) and the cache action.

Author: JamesWrigley

.github/workflows/Docs.yml

@@ -14,6 +14,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-docdeploy@v1
         env:

docs/Project.toml

@@ -4,3 +4,6 @@ IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"
 
 [compat]
 Documenter = "1"
+
+[sources]
+IJulia = {path = ".."}

docs/make.jl

@@ -22,7 +22,6 @@ makedocs(
             "library/internals.md",
         ],
     ],
-    warnonly=true,
 )
 
 # Deploy docs

docs/src/library/internals.md

@@ -35,7 +35,6 @@ IJulia.send_status
 ## Request handlers
 
 ```@docs
-IJulia.handlers
 IJulia.connect_request
 IJulia.execute_request
 IJulia.shutdown_request

src/IJulia.jl

@@ -75,15 +75,19 @@ whether you are in an IJulia notebook, therefore, you can check
 """
 inited = false
 
-# set this to false for debugging, to disable stderr redirection
-"""
+const _capture_docstring = """
 The IJulia kernel captures all [stdout and stderr](https://en.wikipedia.org/wiki/Standard_streams)
 output and redirects it to the notebook.   When debugging IJulia problems,
 however, it can be more convenient to *not* capture stdout and stderr output
 (since the notebook may not be functioning). This can be done by editing
 `IJulia.jl` to set `capture_stderr` and/or `capture_stdout` to `false`.
 """
+
+@doc _capture_docstring
 const capture_stdout = true
+
+# set this to false for debugging, to disable stderr redirection
+@doc _capture_docstring
 const capture_stderr = !IJULIA_DEBUG
 
 set_current_module(m::Module) = current_module[] = m

src/display.jl

@@ -40,8 +40,21 @@ const ijulia_jsonmime_types = Vector{Union{MIME, Vector{MIME}}}([
     MIME("application/vnd.dataresource+json"), MIME("application/vnd.plotly.v1+json")
 ])
 
-register_mime(x::Union{MIME, Vector{MIME}})= push!(ijulia_mime_types, x)
+"""
+    register_mime(x::Union{MIME, Vector{MIME}})
+    register_mime(x::AbstractVector{<:MIME})
+
+Register a new MIME type.
+"""
+register_mime(x::Union{MIME, Vector{MIME}}) = push!(ijulia_mime_types, x)
 register_mime(x::AbstractVector{<:MIME}) = push!(ijulia_mime_types, Vector{Mime}(x))
+
+"""
+    register_jsonmime(x::Union{MIME, Vector{MIME}})
+    register_jsonmime(x::AbstractVector{<:MIME})
+
+Register a new JSON MIME type.
+"""
 register_jsonmime(x::Union{MIME, Vector{MIME}}) = push!(ijulia_jsonmime_types, x)
 register_jsonmime(x::AbstractVector{<:MIME}) = push!(ijulia_jsonmime_types, Vector{Mime}(x))
 
@@ -92,8 +105,8 @@ display_mimejson(m::MIME, x) = (m, JSON.JSONText(limitstringmime(m, x, true)))
 
 """
 Generate a dictionary of `mime_type => data` pairs for all registered MIME
-types. This is the format that Jupyter expects in display_data and
-execute_result messages.
+types. This is the format that Jupyter expects in `display_data` and
+`execute_result` messages.
 """
 function display_dict(x)
     data = Dict{String, Union{String, JSONText}}()

src/eventloop.jl

@@ -1,3 +1,9 @@
+"""
+    eventloop(socket)
+
+Generic event loop for one of the [kernel
+sockets](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introduction).
+"""
 function eventloop(socket)
     task_local_storage(:IJulia_task, "write task")
     try
@@ -33,6 +39,13 @@ function eventloop(socket)
 end
 
 const requests_task = Ref{Task}()
+
+"""
+    waitloop()
+
+Main loop of a kernel. Runs the event loops for the control and shell sockets
+(note: in IJulia the shell socket is called `requests`).
+"""
 function waitloop()
     @async eventloop(control[])
     requests_task[] = @async eventloop(requests[])

src/execute_request.jl

@@ -24,6 +24,13 @@ import REPL: helpmode
 # use a global array to accumulate "payloads" for the execute_reply message
 const execute_payloads = Dict[]
 
+"""
+    execute_request(socket, msg)
+
+Handle a [execute
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute).
+This will execute Julia code, along with Pkg and shell commands.
+"""
 function execute_request(socket, msg)
     code = msg.content["code"]
     @vprintln("EXECUTING ", code)

src/handlers.jl

@@ -108,6 +108,12 @@ function complete_types(comps)
     return typeMap
 end
 
+"""
+    complete_request(socket, msg)
+
+Handle a [completion
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#completion).
+"""
 function complete_request(socket, msg)
     code = msg.content["code"]
     cursor_chr = msg.content["cursor_pos"]
@@ -153,6 +159,12 @@ function complete_request(socket, msg)
                                                   "cursor_end" => cursor_end)))
 end
 
+"""
+    kernel_info_request(socket, msg)
+
+Handle a [kernel info
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-info).
+"""
 function kernel_info_request(socket, msg)
     send_ipython(socket,
                  msg_reply(msg, "kernel_info_reply",
@@ -179,21 +191,34 @@ function kernel_info_request(socket, msg)
                                         "status" => "ok")))
 end
 
+"""
+    connect_request(socket, msg)
+
+Handle a [connect
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#connect).
+"""
 function connect_request(socket, msg)
     send_ipython(requests[],
                  msg_reply(msg, "connect_reply",
                            Dict("shell_port" => profile["shell_port"],
-                                        "iopub_port" => profile["iopub_port"],
-                                        "stdin_port" => profile["stdin_port"],
-                                        "hb_port" => profile["hb_port"])))
+                                "iopub_port" => profile["iopub_port"],
+                                "stdin_port" => profile["stdin_port"],
+                                "hb_port" => profile["hb_port"])))
 end
 
+"""
+    shutdown_request(socket, msg)
+
+Handle a [shutdown
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-shutdown). After
+sending the reply this will exit the process.
+"""
 function shutdown_request(socket, msg)
     # stop heartbeat thread by closing the context
     close(heartbeat_context[])
 
     send_ipython(requests[], msg_reply(msg, "shutdown_reply",
-                                     msg.content))
+                                       msg.content))
     sleep(0.1) # short delay (like in ipykernel), to hopefully ensure shutdown_reply is sent
     exit()
 end
@@ -235,6 +260,12 @@ function get_token(code, pos)
     return code[startpos:endpos]
 end
 
+"""
+    inspect_request(socket, msg)
+
+Handle a [introspection
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introspection).
+"""
 function inspect_request(socket, msg)
     try
         code = msg.content["code"]
@@ -256,6 +287,13 @@ function inspect_request(socket, msg)
     end
 end
 
+"""
+    history_request(socket, msg)
+
+Handle a [history
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#history). This
+is currently only a dummy implementation that doesn't actually do anything.
+"""
 function history_request(socket, msg)
     # we will just send back empty history for now, pending clarification
     # as requested in ipython/ipython#3806
@@ -264,6 +302,12 @@ function history_request(socket, msg)
                            Dict("history" => [])))
 end
 
+"""
+    is_complete_request(socket, msg)
+
+Handle a [completeness
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#code-completeness).
+"""
 function is_complete_request(socket, msg)
     ex = Meta.parse(msg.content["code"], raise=false)
     status = Meta.isexpr(ex, :incomplete) ? "incomplete" : Meta.isexpr(ex, :error) ? "invalid" : "complete"
@@ -272,6 +316,13 @@ function is_complete_request(socket, msg)
                            Dict("status"=>status, "indent"=>"")))
 end
 
+"""
+    interrupt_request(socket, msg)
+
+Handle a [interrupt
+request](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-interrupt). This
+will throw an `InterruptException` to the currently executing request handler.
+"""
 function interrupt_request(socket, msg)
     @async Base.throwto(requests_task[], InterruptException())
     send_ipython(socket, msg_reply(msg, "interrupt_reply", Dict()))

src/init.jl

@@ -45,6 +45,13 @@ const socket_locks = Dict{Socket,ReentrantLock}()
     const minirepl = Ref{MiniREPL}()
 end
 
+"""
+    init(args)
+
+Initialize a kernel. `args` may either be empty or have one element containing
+the path to an existing connection file. If `args` is empty a connection file
+will be generated.
+"""
 function init(args)
     inited && error("IJulia is already running")
     if length(args) > 0