docs

Christopher Doris · Christopher Doris · commit c22bdd52bb15 · 2021-10-23T19:10:36.000+01:00
diff --git a/README.md b/README.md
@@ -21,19 +21,19 @@ To get started, read the [documentation](https://cjdoris.github.io/PythonCall.jl
 
 ## Example 1: Calling Python from Julia
 
-In this example, we use `PythonCall.jl` from a [`Pluto`](https://github.com/fonsp/Pluto.jl) notebook to inspect the Iris dataset:
-- We load the Iris dataset as a Julia [`DataFrame`](https://dataframes.juliadata.org/stable/) using [`RDatasets.jl`](https://github.com/JuliaStats/RDatasets.jl).
-- We use `pytable(df)` to convert it to a Python [`pandas.DataFrame`](https://pandas.pydata.org/).
-- We use the Python package [`seaborn`](https://seaborn.pydata.org/) to produce a pair-plot, which is automatically displayed.
+In this example, we use PythonCall from a [Pluto](https://github.com/fonsp/Pluto.jl) notebook to inspect the Iris dataset:
+- We load the Iris dataset as a Julia [DataFrame](https://dataframes.juliadata.org/stable/) using [RDatasets](https://github.com/JuliaStats/RDatasets.jl).
+- We use `pytable(df)` to convert it to a Python [Pandas DataFrame](https://pandas.pydata.org/).
+- We use the Python package [Seaborn](https://seaborn.pydata.org/) to produce a pair-plot, which is automatically displayed.
 
 ![Seaborn example screenshot](https://raw.githubusercontent.com/cjdoris/PythonCall.jl/master/examples/seaborn.png)
 
 ## Example 2: Calling Julia from Python
 
-In this example we use the Python module `juliacall` from an IPython notebook to train a simple neural network:
-- We generate some random training data using Python's `numpy`.
-- We construct and train a neural network model using Julia's `Flux`.
-- We plot some sample output from the model using Python's `matplotlib.pyplot`.
+In this example we use the Python module JuliaCall from an IPython notebook to train a simple neural network:
+- We generate some random training data using Python's Numpy.
+- We construct and train a neural network model using Julia's Flux.
+- We plot some sample output from the model using Python's MatPlotLib.
 
 ![Flux example screenshot](https://raw.githubusercontent.com/cjdoris/PythonCall.jl/master/examples/flux.png)
 
diff --git a/docs/src/conversion-to-julia.md b/docs/src/conversion-to-julia.md
@@ -1,18 +1,12 @@
 # [Conversion to Julia](@id py2jl)
 
-## Conversion Rules
+## [Conversion Rules](@id py2jl-conversion)
 
-From Julia, one can convert Python objects to a desired type using `pyconvert(T, x)` for example.
-
-From Python, when a value is passed to Julia, it is typically converted to a corresponding Julia value using `pyconvert(Any, x)`.
+The following table specifies the conversion rules used whenever converting a Python object to a Julia object. If the initial Python type matches the "From" column and the desired type `T` intersects with the "To" column, then that conversion is attempted. Conversions are tried in priority order, then in specificity order.
 
-Quite general conversions are allowed, and the target type `T` can be as specific as you like. For example
-```
-@pyv `[1, None, 3]`::Tuple{Vararg{Union{AbstractFloat,Missing}}}
-```
-evaluates to `(1.0, missing, 2.0)`.
+From Julia, one can convert Python objects to a desired type using `pyconvert(T, x)` for example.
 
-The following table specifies the conversion rules in place. If the initial Python type matches the "From" column and the desired type `T` intersects with the "To" column, then that conversion is attempted. Conversions are tried in priority order, then in specificity order.
+From Python, the arguments to a Julia function will be converted according to these rules with `T=Any`.
 
 | From                                                                                                         | To                                                          |
 | :----------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |
diff --git a/docs/src/conversion-to-python.md b/docs/src/conversion-to-python.md
@@ -1,14 +1,13 @@
 # [Conversion to Python](@id jl2py)
 
-## Conversion Rules
-
-From Julia, one converts Julia objects to Python explicitly using `Py(x)` or implicitly by passing the value to one of the many other functions, such as `pygetattr(x, "append")`.
-
-From Python, calling a Julia function or indexing a Julia object, etc., will convert the result to some Python object.
+## [Conversion Rules](@id jl2py-conversion)
 
 The following table specifies the conversion rules used whenever converting a Julia object to a Python object.
 
-The user can always explicitly choose a different conversion (e.g. by calling `pylist` or `pydict`).
+From Julia, this occurs explicitly with `Py(x)` or implicitly when passing Julia objects as the argument to a Python function.
+To avoid this automatic conversion, the user can convert objects explicitly, such as by calling `pylist` or `pydict`.
+
+From Python, this occurs when converting the return value of a Julia function.
 
 | From                                                                | To                                                      |
 | :------------------------------------------------------------------ | :------------------------------------------------------ |
diff --git a/docs/src/juliacall.md b/docs/src/juliacall.md
@@ -1,51 +1,68 @@
-# The Python module *juliacall*
+# The Python module JuliaCall
 
 ## Installation
 
-In the future, the package will be available on PyPI and conda.
-For now, you can pip install this package directly from github as follows:
-
+It's as simple as
 ```bash
-pip install git+https://github.com/cjdoris/PythonCall.jl
+pip install juliacall
 ```
 
-Developers may wish to clone the repo directly and pip install the module in editable mode.
-This guarantees you are using the latest version of PythonCall in conjunction with juliacall.
-
-Note also that regardless of installing `juliacall`, a module called `juliacall` will
-always be loaded into the interpreter by `PythonCall`. This means that other Python
-packages can always `import juliacall`.
+Developers may wish to clone the repo (https://github.com/cjdoris/PythonCall.jl) directly
+and pip install the module in editable mode. This guarantees you are using the latest
+version of PythonCall in conjunction with JuliaCall.
 
 ## Getting started
 
 For interactive or scripting use, the simplest way to get started is:
-
 ```python
 from juliacall import Main as jl
 ```
 
-This loads a single variable `jl` (a [`ModuleValue`](#juliacall.ModuleValue)) which represents the `Main` module in Julia, from which all of Julia's functionality is available.
+This loads a single variable `jl` which represents the `Main` module in Julia,
+from which all of Julia's functionality is available:
+```python
+jl.println("Hello from Julia!")
+# Hello from Julia!
+x = jl.rand(range(10), 3, 5)
+x._jl_display()
+# 3×5 Matrix{Int64}:
+#  8  1  7  0  6
+#  9  2  1  4  0
+#  1  8  5  4  0
+import numpy
+numpy.sum(x, axis=0)
+# array([18, 11, 13,  8,  6], dtype=int64)
+```
 
-If you are writing a package which uses Julia, then to avoid polluting the global `Main` namespace you should do:
+In this example:
+- We called the `jl.println` function to print a message.
+- We called the `jl.rand` function to generate an array of random integers. Note that the
+  first argument is `range(10)` which is converted to `0:9` in Julia.
+- We called its special `_jl_display()` to show it using Julia's display mechanism.
+- We called the `numpy.sum` function to sum each column of `x`. This automatically converted
+  `x` to a NumPy array. (We could have done `jl.sum(x, dims=1)` too.)
 
+If you are writing a package which uses Julia, then to avoid polluting the global `Main`
+namespace you instead should start with:
 ```python
 import juliacall; jl = juliacall.newmodule("SomeName");
 ```
 
-Now you can do `jl.rand(jl.Bool, 5, 5)`, which is equivalent to `rand(Bool, 5, 5)` in Julia.
-
-When a Python value is passed to Julia, then typically it will be converted according to [this table](@ref py2jl) with `T=Any`.
-Sometimes a more specific type will be used, such as when assigning to an array whose element type is known.
-
-When a Julia value is returned to Python, it will normally be converted according to [this table](@ref jl2py).
+What to read next:
+- The main functionality of this package is in `AnyValue` objects, which represent Julia
+  objects, [documented here](@ref julia-wrappers).
+- If you need to install Julia packages, [read here](@ref julia-deps).
+- When you call a Julia function, such as `jl.rand(...)` in the above example, its
+  arguments are converted to Julia according to [this table](@ref py2jl-conversion) and
+  its return value is converted to Python according to [this table](@ref jl2py-conversion).
 
-## Managing Julia dependencies
+## [Managing Julia dependencies](@id julia-deps)
 
-juliacall manages its Julia dependencies using [Pkg](https://pkgdocs.julialang.org/v1) for
+JuliaCall manages its Julia dependencies using [Pkg](https://pkgdocs.julialang.org/v1) for
 packages and [jill](https://pypi.org/project/jill/) for Julia itself.
-If a suitable version of julia is not found on your system, it will automatically be
+If a suitable version of Julia is not found on your system, it will automatically be
 downloaded and installed into `~/.julia/pythoncall`.
-A Julia environment is automatically created when juliacall is loaded, is activated, and is
+A Julia environment is automatically created when JuliaCall is loaded, is activated, and is
 initialised with at least PythonCall. If you are using a virtual or conda environment then
 the Julia environment is created there, otherwise a global environment is created at
 `~/.julia/environments/PythonCall`.
@@ -74,9 +91,10 @@ Here is an example:
     }
 }
 ```
-All parts are optional, except that the UUID of each package is required.
+All parts are optional, except that the UUID of each package is required. Typically you
+will just include the UUID and compat fields.
 
-When juliacall starts, it will ensure the latest compatible version of julia is installed,
+When JuliaCall starts, it will ensure the latest compatible version of Julia is installed,
 and will ensure the given packages are installed.
 
 ## Utilities
diff --git a/docs/src/pycall.md b/docs/src/pycall.md
@@ -1,6 +1,6 @@
 # Coming from *PyCall*?
 
-Another similar interface to Python is provided by [`PyCall`](https://github.com/JuliaPy/PyCall.jl).
+Another similar interface to Python is provided by [PyCall](https://github.com/JuliaPy/PyCall.jl).
 
 On this page, we give some tips for migrating between the two modules and a comparison.
 
@@ -61,11 +61,11 @@ PythonCall uses a separate Conda environment for each Julia environment/project/
 
 ### Corresponding Python packages
 
-PyCall has the corresponding Python package [pyjulia](https://github.com/JuliaPy/pyjulia) for calling Julia from Python, and PythonCall similarly has juliacall.
+PyCall has the corresponding Python package [PyJulia](https://github.com/JuliaPy/pyjulia) for calling Julia from Python, and PythonCall similarly has JuliaCall.
 
-One difference is between them is their code size: pyjulia is a large package, whereas juliacall is very small, with most of the implementation being in PythonCall itself. The practical up-shot is that PythonCall/juliacall have very symmetric interfaces; for example they use identical conversion policies and have the same set of wrapper types available.
+One difference is between them is their code size: PyJulia is a large package, whereas JuliaCall is very small, with most of the implementation being in PythonCall itself. The practical up-shot is that PythonCall/JuliaCall have very symmetric interfaces; for example they use identical conversion policies and have the same set of wrapper types available.
 
-Note also that juliacall will use a separate Julia project for each virtual/conda environment. This means that different Python environments can maintain an isolated set of Julia dependencies, including the versions of Julia and PythonCall themselves.
+Note also that JuliaCall will use a separate Julia project for each virtual/conda environment. This means that different Python environments can maintain an isolated set of Julia dependencies, including the versions of Julia and PythonCall themselves.
 
 ### Compatability
 
diff --git a/docs/src/pythoncall.md b/docs/src/pythoncall.md
@@ -1,4 +1,4 @@
-# The Julia module *PythonCall*
+# The Julia module PythonCall
 
 ## Installation
 
@@ -45,7 +45,18 @@ In this example:
 - We called [`pyconvert`](@ref) to convert the Python string `sentence` to a Julia string
   (see [Conversion to Julia](@ref py2jl)).
 
-Read on to find out what else you can do.
+What to read next:
+- The rest of this page details the functions for interacting with Python objects, of type
+  [`Py`](@ref).
+- If you need to install Python packages, [read here](@ref python-deps).
+- When you call a Python function, such as `re.findall(...)` in the above example, its
+  arguments are converted to Python according to [this table](@ref jl2py-conversion) and
+  its return value is a [`Py`](@ref).
+- Python objects can be converted to Julia objects using [`pyconvert`](@ref) with rules
+  according to [this table](@ref py2jl-conversion).
+- Python objects can also be wrapped to provide more Julian semantics. For example, a
+  [`PyDict`](@ref) wraps a Python dict as a Julia dict, and a [`PyArray`](@ref) wraps a
+  Python array or buffer as a Julia array. [See here](@id python-wrappers).
 
 ## `Py`
 
@@ -228,7 +239,7 @@ pyge
 pygt
 ```
 
-## Managing Python dependencies
+## [Managing Python dependencies](@id python-deps)
 
 PythonCall manages its Python dependencies using Conda. A Conda environment is automatically
 created in your active Julia environment when PythonCall is loaded, is initialised with
@@ -237,7 +248,10 @@ at least `python` and `pip`, and is activated.
 If your project requires more Python dependencies, use the mechanisms below to ensure they
 are automatically installed.
 
-We **strongly recommend that you specify Conda dependencies** if possible, instead of pip
+**Do not install packages using conda or pip directly!** PythonCall can and will delete and
+reinstall its Conda environment periodically, such as when any dependencies change.
+
+**We strongly recommend that you specify Conda dependencies** if possible, instead of pip
 or script dependencies. This is because Conda can account for all inter-dependencies between
 packages and so prevent incompatible combinations of packages from being installed.
 
@@ -270,6 +284,8 @@ packages installed, and will run the script if specified.
 Instead of manually editing `PythonCallDeps.toml`, you can use the submodule
 `PythonCall.Deps` to manage the Python dependencies of the current Julia project.
 
+These functions are for interactive use, **do not call them from packages!**
+
 ```@docs
 PythonCall.Deps.status
 PythonCall.Deps.add
@@ -293,7 +309,7 @@ Note that using a non-default interpreter will disable all dependency management
 environment will be created and no packages will be automatically installed. It is up to the
 user to ensure any required packages are installed.
 
-## Writing packages which depend on *PythonCall*
+## Writing packages which depend on PythonCall
 
 ### Example
 
