Documentation fixes and upgrade to Documenter v1 (#1104)

.github/workflows/Docs.yml

@@ -0,0 +1,20 @@
+name: Documenter
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  Documenter:
+    permissions:
+      contents: write
+      statuses: write
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -8,3 +8,4 @@
 *.jl.*.cov
 /docs/src/assets/logo.svg
 /docs/src/assets/favicon.ico
+Manifest*.toml

README.md

@@ -2,7 +2,7 @@
 
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaLang.github.io/IJulia.jl/stable)
 [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaLang.github.io/IJulia.jl/dev)
-[![Build Status](https://github.com/JuliaLang/IJulia.jl/workflows/CI/badge.svg)](https://github.com/JuliaLang/IJulia.jl/actions?query=workflow%3ACI+branch%3Amaster)
+[![Run tests](https://github.com/JuliaLang/IJulia.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/JuliaLang/IJulia.jl/actions/workflows/CI.yml)
 
 # IJulia
 

deps/kspec.jl

@@ -65,7 +65,7 @@ executable, the user-visible kernel name is given by `name` followed by the
 Julia version, and the `env` dictionary is added to the environment.
 
 The new kernel name is returned by `installkernel`.  For example:
-```
+```julia
 kernelpath = installkernel("Julia O3", "-O3", env=Dict("FOO"=>"yes"))
 ```
 creates a new Julia kernel in which `julia` is launched with the `-O3`
@@ -84,7 +84,7 @@ You can specify a custom command to execute Julia via keyword argument
 in a Docker container (but Jupyter will run outside of it), by calling
 `installkernel` from within such a container instance like this (or similar):
 
-```
+```julia
 installkernel(
     "Julia via Docker",
     julia = `docker run --rm --net=host

docs/Project.toml

@@ -1,3 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"
+
+[compat]
+Documenter = "1"

docs/make.jl

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

docs/src/manual/installation.md

@@ -3,10 +3,9 @@
 
 ## Installing IJulia
 
-First, [download Julia](http://julialang.org/downloads/) *version 0.7
-or later* and run the installer.  Then run the Julia application
-(double-click on it); a window with a `julia>` prompt will appear.  After ensuring that you have activated the default Julia environment, at
-the prompt, type:
+First, install Julia from [Download Julia page](http://julialang.org/downloads/).
+Then run the Julia application (double-click on it); a window with a `julia>` prompt will appear.
+After ensuring that you have activated the default Julia environment, at the prompt, type:
 ```julia
 using Pkg
 Pkg.add("IJulia")
@@ -67,7 +66,7 @@ lets you open notebooks with this flag.
 
 You can also install kernels to run Julia with different environment
 variables, for example to set [`JULIA_NUM_THREADS`](https://docs.julialang.org/en/v1/manual/environment-variables/index.html#JULIA_NUM_THREADS-1) for use with Julia [multithreading](https://docs.julialang.org/en/v1/manual/parallel-computing/#Multi-Threading-(Experimental)-1):
-```
+```julia
 using IJulia
 installkernel("Julia (4 threads)", env=Dict("JULIA_NUM_THREADS"=>"4"))
 ```

docs/src/manual/running.md

@@ -26,11 +26,8 @@ in the background that will persist even when you quit Julia.
 This is also useful if you want to keep using the current Julia
 session instead of opening a new one.
 
-```julia
-julia> using IJulia; notebook(detached=true)
-Process(`'C:\Users\JuliaUser\.julia\v0.7\Conda\deps\usr\Scripts\jupyter' notebook`, ProcessRunning)
-
-julia>
+```@repl
+using IJulia; notebook(detached=true)
 ```
 
 By default, the notebook "dashboard" opens in your
@@ -67,7 +64,7 @@ other Julia file (including another notebook) via the [NBInclude](https://github
 
 Instead of running the classic notebook interface, you can use the IDE-like JupyterLab. If you are comfortable managing your own JupyterLab installation, you can just run `jupyter lab` yourself in a terminal.   To simplify installation, however, you can alternatively type the following in Julia, at the `julia>` prompt:
 
-```jl
+```julia
 using IJulia
 jupyterlab()
 ```

docs/src/manual/troubleshooting.md

@@ -21,7 +21,7 @@ If IJulia is crashing (e.g. it gives you a "kernel appears to have
 died" message), you can modify it to print more descriptive error
 messages to the terminal by doing:
 
-```jl
+```julia
 ENV["IJULIA_DEBUG"]=true
 Pkg.build("IJulia")
 ```

docs/src/manual/usage.md

@@ -93,7 +93,7 @@ old inputs and outputs, simply index into them, e.g. `In[1]` or `Out[5]`. Someti
 may find themselves outputting large matrices or other datastructures which
 will be stored in `Out` and hence not garbage collected, possibly hogging memory.
 If you find that IJulia is using too much memory after generating large outputs, empty this output dictionary:
-```
+```julia
 empty!(Out)
 ```
 

src/magics.jl

@@ -197,7 +197,7 @@ prun_magic_help(magic::AbstractString, args::AbstractString) = md"""
     `@profile statement`, which runs the
     [Julia profiler](http://docs.julialang.org/en/latest/manual/profile/).
     The analogue of `%%prun ...code...` is
-    ```
+    ```julia
     @profile begin
         ...code...
     end
@@ -242,7 +242,7 @@ run_magic_help(magic::AbstractString, args::AbstractString) = md"""
 
 save_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%save filename n1-n2 n3-n4` is
-    ```
+    ```julia
     open("filename","w") do io
         for i in [n1:n2; n3:n4]
             println(get(In,i,""))
@@ -268,7 +268,7 @@ Markdown.parse("""
 time_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%time statement` (also `%timeit`) in Julia is
     `@time statement`.  The analogue of `%%time ...code...` is
-    ```
+    ```julia
     @time begin
         ...code...
     end
@@ -294,7 +294,7 @@ who_magic_help(magic::AbstractString, args::AbstractString) = md"""
 
 html_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%%html` is
-    ```
+    ```julia
     HTML(""\"
     ...html text...
     ""\")
@@ -304,12 +304,12 @@ html_magic_help(magic::AbstractString, args::AbstractString) = md"""
 javascript_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%%javascript ...code...` in Julia can be
     constructed by first evaluating
-    ```
+    ```julia
     macro javascript_str(s) display("text/javascript", s); end
     ```
     to define the `javascript"...."` [string macro](http://docs.julialang.org/en/latest/manual/strings/#non-standard-string-literals)
     in Julia.  Subsequently, you can simply do:
-    ```
+    ```julia
     javascript""\"
     ...code...
     ""\"
@@ -318,7 +318,7 @@ javascript_magic_help(magic::AbstractString, args::AbstractString) = md"""
 
 latex_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%%latex` is
-    ```
+    ```julia
     display("text/latex", ""\"
     ...latex text...
     ""\")
@@ -344,12 +344,12 @@ function pipe_magic_help(magic::AbstractString, args::AbstractString)
     Markdown.parse("""
     The analogue of IPython's `$magic ...code...` in Julia can be
     constructed by first evaluating
-    ```
+    ```julia
     macro $(cmd)_str(s) open(`$cmd`,"w",stdout) do io; print(io, s); end; end
     ```
     to define the `$cmd"...."` [string macro](http://docs.julialang.org/en/latest/manual/strings/#non-standard-string-literals)
     in Julia.  Subsequently, you can simply do:
-    ```
+    ```julia
     $cmd""\"
     ...code...
     ""\"
@@ -359,18 +359,18 @@ end
 
 svg_magic_help(magic::AbstractString, args::AbstractString) = md"""
     The analogue of IPython's `%%svg` is
-    ```
+    ```julia
     display("image/svg+xml", ""\"
     ...svg text...
     ""\")
     ```
     in Julia. To be even nicer, you can define
-    ```
+    ```julia
     macro svg_str(s) display("image/svg+xml", s); end
     ```
     to define the `svg"...."` [string macro](http://docs.julialang.org/en/latest/manual/strings/#non-standard-string-literals)
     in Julia.  Subsequently, you can simply do:
-    ```
+    ```julia
     svg""\"
     ...svg text...
     ""\"