Add documentation with Documenter.jl (#941)

jlumpe · web-flow · commit 37b7bacd965d · 2020-08-14T10:58:45.000-04:00
* Documenter.jl src files with README contents * Add public API docs page w/ @AutoDoc, empty docs page on internals * Simplify README * Set up documentation deployment * Add documentation badges to README * Run Pkg.build() in documentation workflow
diff --git a/.github/workflows/documentation-workflow.yml b/.github/workflows/documentation-workflow.yml
@@ -0,0 +1,24 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: 'v*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.4'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); Pkg.build("IJulia")'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl
diff --git a/README.md b/README.md
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,26 @@
+using Documenter, IJulia
+
+
+makedocs(
+    modules=[IJulia],
+    sitename="IJulia",
+    pages=[
+        "Home" => "index.md",
+        "Manual" => [
+            "manual/installation.md",
+            "manual/running.md",
+            "manual/usage.md",
+            "manual/troubleshooting.md",
+        ],
+        "Library" => [
+            "library/public.md",
+            "library/internals.md",
+        ],
+    ],
+)
+
+
+deploydocs(
+    repo = "github.com/JuliaLang/IJulia.jl.git",
+    push_preview = true,
+)
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,14 @@
+# IJulia
+
+**IJulia** is a [Julia-language](http://julialang.org/) backend
+combined with the [Jupyter](http://jupyter.org/) interactive
+environment (also used by [IPython](http://ipython.org/)).  This
+combination allows you to interact with the Julia language using
+Jupyter/IPython's powerful [graphical
+notebook](http://ipython.org/notebook.html), which combines code,
+formatted text, math, and multimedia in a single document.  It
+also works with [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), a Jupyter-based
+integrated development environment for notebooks and code.
+
+(IJulia notebooks can also be re-used in other Julia code via
+the [NBInclude](https://github.com/stevengj/NBInclude.jl) package.)
diff --git a/docs/src/internals.md b/docs/src/internals.md
diff --git a/docs/src/library/internals.md b/docs/src/library/internals.md
@@ -0,0 +1,3 @@
+# Internals
+
+TODO
diff --git a/docs/src/library/public.md b/docs/src/library/public.md
@@ -0,0 +1,6 @@
+# Public API
+
+
+```@autodocs
+Modules = [ IJulia ]
+```
diff --git a/docs/src/manual/installation.md b/docs/src/manual/installation.md
@@ -0,0 +1,125 @@
+# Installation
+
+
+## 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.  At
+the prompt, type:
+```julia
+using Pkg
+Pkg.add("IJulia")
+```
+to install IJulia.
+
+This process installs a [kernel specification](https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernelspecs) that tells Jupyter (or JupyterLab) etcetera
+how to launch Julia.
+
+`Pkg.add("IJulia")` does not actually install Jupyter itself.
+You can install Jupyter if you want, but it can also be installed
+automatically when you run `IJulia.notebook()` below.  (You
+can force it to use a specific `jupyter` installation by
+setting `ENV["JUPYTER"]` to the path of the `jupyter` program
+before `Pkg.add`, or before running `Pkg.build("IJulia")`;
+your preference is remembered on subsequent updates.
+
+
+## Updating Julia and IJulia
+
+Julia is improving rapidly, so it won't be long before you want to
+update to a more recent version.  To update the packages only, keeping
+Julia itself the same, just run:
+```julia
+Pkg.update()
+```
+at the Julia prompt (or in IJulia).
+
+If you download and install a new version of Julia from the Julia web
+site, you will also probably want to update the packages with
+`Pkg.update()` (in case newer versions of the packages are required
+for the most recent Julia).  In any case, if you install a new Julia
+binary (or do anything that *changes the location of Julia* on your
+computer), you *must* update the IJulia installation (to tell Jupyter
+where to find the new Julia) by running
+```julia
+Pkg.build("IJulia")
+```
+at the Julia command line (**important**: not in IJulia).
+
+
+## Installing additional Julia kernels
+
+You can also install additional Julia kernels, for example, to
+pass alternative command-line arguments to the `julia` executable,
+by using the `IJulia.installkernel` function.  See the help for this
+function (`? IJulia.installkernel` in Julia) for complete details.
+
+For example, if you want to run Julia with all deprecation warnings
+disabled, you can do:
+```julia
+using IJulia
+installkernel("Julia nodeps", "--depwarn=no")
+```
+and a kernel called `Julia nodeps 0.7` (if you are using Julia 0.7)
+will be installed (will show up in your main Jupyter kernel menu) that
+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):
+```
+using IJulia
+installkernel("Julia (4 threads)", env=Dict("JULIA_NUM_THREADS"=>"4"))
+```
+The `env` keyword should be a `Dict` mapping environment variables to values.
+
+
+## Low-level Information
+
+### Using older IPython versions
+
+While we strongly recommend using IPython version 3 or later (note that this
+has nothing to do with whether you use Python version 2 or 3), we recognize
+that in the short term some users may need to continue using IPython 2.x.  You
+can do this by checkout out the `ipython2` branch of the IJulia package:
+
+```julia
+Pkg.checkout("IJulia", "ipython2")
+Pkg.build("IJulia")
+```
+
+### Manual installation of IPython
+
+First, you will need to install a few prerequisites:
+
+* You need **version 3.0** or later of IPython, or version 4 or later
+of Jupyter.  Note that IPython 3.0 was released in February 2015, so
+if you have an older operating system you may
+have to [install IPython
+manually](http://ipython.org/ipython-doc/stable/install/install.html).
+On Mac and Windows systems, it is currently easiest to use the
+[Anaconda Python](http://continuum.io/downloads) installer.
+
+* To use the [IPython notebook](http://ipython.org/notebook.html) interface, which runs in your web
+  browser and provides a rich multimedia environment, you will need
+  to install the [jsonschema](https://pypi.python.org/pypi/jsonschema), [Jinja2](http://jinja.pocoo.org/docs/), [Tornado](http://www.tornadoweb.org/en/stable/),
+  and [pyzmq](https://github.com/zeromq/pyzmq) (requires `apt-get install libzmq-dev` and possibly `pip install --upgrade --force-reinstall pyzmq` on Ubuntu if you are using `pip`) Python packages.
+  (Given the [pip](http://www.pip-installer.org/en/latest/) installer, `pip install jsonschema jinja2 tornado pyzmq`
+  should normally be sufficient.)  These should have been automatically installed if you installed IPython itself
+  [via `easy_install` or `pip`](http://ipython.org/ipython-doc/stable/install/install.html#quickstart).
+
+* To use the [IPython qtconsole](http://ipython.org/ipython-doc/dev/interactive/qtconsole.html) interface,
+  you will need to install [PyQt4](http://www.riverbankcomputing.com/software/pyqt/download) or
+  [PySide](http://qt-project.org/wiki/Category:LanguageBindings::PySide).
+
+* You need Julia version 0.7 or later.
+
+Once IPython 3.0+ and Julia 0.7+ are installed, you can install IJulia from a Julia console by typing:
+```julia
+Pkg.add("IJulia")
+```
+This will download IJulia and a few other prerequisites, and will set up a
+Julia kernel for IPython.
+
+If the command above returns an error, you may need to run `Pkg.update()`, then
+retry it, or possibly run `Pkg.build("IJulia")` to force a rebuild.
diff --git a/docs/src/manual/running.md b/docs/src/manual/running.md
@@ -0,0 +1,91 @@
+# Running IJulia
+
+
+## Running the IJulia Notebook
+
+If you are comfortable managing your own Python/Jupyter installation, you can just run `jupyter notebook` yourself in a terminal.   To simplify installation, however, you can alternatively type the following in Julia, at the `julia>` prompt:
+```julia
+using IJulia
+notebook()
+```
+to launch the IJulia notebook in your browser.
+
+The first time you run `notebook()`, it will prompt you
+for whether it should install Jupyter.  Hit enter to
+have it use the [Conda.jl](https://github.com/Luthaf/Conda.jl)
+package to install a minimal Python+Jupyter distribution (via
+[Miniconda](http://conda.pydata.org/docs/install/quick.html)) that is
+private to Julia (not in your `PATH`).
+On Linux, it defaults to looking for `jupyter` in your `PATH` first,
+and only asks to installs the Conda Jupyter if that fails; you can force
+it to use Conda on Linux by setting `ENV["JUPYTER"]=""` during installation (see above).  (In a Debian or Ubuntu  GNU/Linux system, install the package `jupyter-client` to install the system `jupyter`.)
+
+You can
+use `notebook(detached=true)` to launch a notebook server
+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>
+```
+
+By default, the notebook "dashboard" opens in your
+home directory (`homedir()`), but you can open the dashboard
+in a different directory with `notebook(dir="/some/path")`.
+
+Alternatively, you can run
+```
+jupyter notebook
+```
+from the command line (the
+[Terminal](https://en.wikipedia.org/wiki/Terminal_%28OS_X%29) program
+in MacOS or the [Command
+Prompt](https://en.wikipedia.org/wiki/Command_Prompt) in Windows).
+Note that if you installed `jupyter` via automated Miniconda installer
+in `Pkg.add`, above, then `jupyter` may not be in your `PATH`; type
+`import Conda; Conda.SCRIPTDIR` in Julia to find out where Conda
+installed `jupyter`.
+
+A "dashboard" window like this should open in your web browser.  Click
+on the *New* button and choose the *Julia* option to start a new
+"notebook".  A notebook will combine code, computed results, formatted
+text, and images, just as in IPython.  You can enter multiline input
+cells and execute them with *shift-ENTER*, and the menu items are
+mostly self-explanatory.  Refer to [the Jupyter notebook
+documentation](https://jupyter-notebook.readthedocs.io/en/stable/) for more
+information, and see also the "Help" menu in the notebook itself.
+
+Given an IJulia notebook file, you can execute its code within any
+other Julia file (including another notebook) via the [NBInclude](https://github.com/stevengj/NBInclude.jl) package.
+
+
+## Running the JupyterLab
+
+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
+using IJulia
+jupyterlab()
+```
+
+Like `notebook()`, above, this will install JupyterLab via Conda if it is
+not installed already.   `jupyterlab()` also supports `detached` and `dir` keyword options similar to `notebook()`.
+
+
+## Running nteract
+
+The [nteract Desktop](https://nteract.io/) is an application that lets you work with notebooks without a Python installation. First, install IJulia (but do not run `notebook()` unless you want a Python installation) and then nteract.
+
+
+## Other IPython interfaces
+
+Most people will use the notebook (browser-based) interface, but you
+can also use the IPython
+[qtconsole](http://ipython.org/ipython-doc/dev/interactive/qtconsole.html)
+or IPython terminal interfaces by running `ipython qtconsole --kernel
+julia-0.7` or `ipython console --kernel julia-0.7`, respectively.
+(Replace `0.7` with whatever major Julia version you are using.)
diff --git a/docs/src/manual/troubleshooting.md b/docs/src/manual/troubleshooting.md
@@ -0,0 +1,35 @@
+# Troubleshooting
+
+
+## General troubleshooting tips
+
+* If you ran into a problem with the above steps, after fixing the
+problem you can type `Pkg.build()` to try to rerun the install scripts.
+* If you tried it a while ago, try running `Pkg.update()` and try again:
+  this will fetch the latest versions of the Julia packages in case
+  the problem you saw was fixed.  Run `Pkg.build("IJulia")` if your Julia version may have changed.  If this doesn't work, you could try just deleting the whole `.julia` directory in your home directory (on Windows, it is called `Users\USERNAME\.julia` in your home directory) via `rm(Pkg.dir(),recursive=true)` in Julia and re-adding the packages.
+* On MacOS, you currently need MacOS 10.7 or later; [MacOS 10.6 doesn't work](https://github.com/JuliaLang/julia/issues/4215) (unless you compile Julia yourself, from source code).
+* Internet Explorer 8 (the default in Windows 7) or 9 don't work with the notebook; use Firefox (6 or later) or Chrome (13 or later).  Internet Explorer 10 in Windows 8 works (albeit with a few rendering glitches), but Chrome or Firefox is better.
+* If the notebook opens up, but doesn't respond (the input label is `In[*]` indefinitely), try creating a new Python notebook (not Julia) from the `New` button in the Jupyter dashboard, to see if `1+1` works in Python.  If it is the same problem, then probably you have a [firewall running](https://github.com/ipython/ipython/issues/2499) on your machine (this is common on Windows) and you need to disable the firewall or at least to allow the IP address 127.0.0.1.  (For the [Sophos](https://en.wikipedia.org/wiki/Sophos) endpoint security software, go to "Configure Anti-Virus and HIPS", select "Authorization" and then "Websites", and add 127.0.0.1 to "Authorized websites"; finally, restart your computer.)
+* Try running `jupyter --version` and make sure that it prints `3.0.0` or larger; earlier versions of IPython are no longer supported by IJulia.
+* You can try setting `ENV["JUPYTER"]=""; Pkg.build("IJulia")` to force IJulia to go back to its own Conda-based Jupyter version (if you previously tried a different `jupyter`).
+
+
+## Debugging IJulia problems
+
+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
+ENV["IJULIA_DEBUG"]=true
+Pkg.build("IJulia")
+```
+
+Restart the notebook and look for the error message when IJulia dies.
+(This changes IJulia to default to `verbose = true` mode, and sets
+`capture_stderr = false`, hopefully sending a bunch of debugging to
+the terminal where you launched `jupyter`).
+
+When you are done, set `ENV["IJULIA_DEBUG"]=false` and re-run
+`Pkg.build("IJulia")` to turn off the debugging output.
diff --git a/docs/src/manual/usage.md b/docs/src/manual/usage.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[deps]`
	`2`	`+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"`
	`3`	`+IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"`