docs

Author: Christopher Doris

docs/make.jl

@@ -35,13 +35,19 @@ makedocs(
     modules = [PythonCall],
     pages = [
         "Home" => "index.md",
-        "pythoncall.md",
-        "juliacall.md",
-        "conversion-to-python.md",
-        "conversion-to-julia.md",
+        "The Julia module PythonCall" => [
+            "Guide" => "pythoncall.md",
+            "Reference" => "pythoncall-reference.md",
+        ],
+        "The Python module JuliaCall" => [
+            "Guide" => "juliacall.md",
+            "Reference" => "juliacall-reference.md",
+        ],
+        "Conversion" => [
+            "Julia to Python" => "conversion-to-python.md",
+            "Python to Julia" => "conversion-to-julia.md",
+        ],
         "compat.md",
-        "pythoncall-reference.md",
-        "juliacall-reference.md",
         "pycall.md",
         "releasenotes.md",
     ]

docs/src/compat.md

@@ -10,11 +10,17 @@ Whenever a Python exception is displayed by Julia, `sys.last_traceback` and frie
 
 ## Tabular data & Pandas
 
-A `pandas.DataFrame` can be wrapped in Julia as a [`PyPandasDataFrame`](@ref), providing a `Tables.jl`-compatible interface.
+The abstract type [`PyTable`](@ref) is for wrapper types around Python tables, providing the
+[Tables.jl](https://github.com/JuliaData/Tables.jl) interface. `PyTable(x)` is shorthand
+for `pyconvert(PyTable, x)`.
 
-Furthermore, any Python object which can be converted to a `PyTable` (e.g. `pandas.DataFrame` can be converted to `PyPandasDataFrame`) satisfies the Tables.jl interface.
+The subtype [`PyPandasDataFrame`](@ref) wraps a `pandas.DataFrame`.
 
-In the other direction, the following functions can be used to convert any `Tables.jl`-compatible table to a Python table.
+For example, if `x` is a `pandas.DataFrame` then `PyTable(x)` is a `PyPandasDataFrame` and
+`DataFrame(PyTable(x))` is a [`DataFrame`](https://github.com/JuliaData/DataFrames.jl).
+
+In the other direction, the following functions can be used to convert any
+`Tables.jl`-compatible table to a Python table.
 
 ```@docs
 pytable

docs/src/pythoncall-reference.md

@@ -1,4 +1,4 @@
-# PythonCall API Reference
+# [PythonCall API Reference](@id py-reference)
 
 ## `Py` objects
 

docs/src/pythoncall.md

@@ -64,7 +64,7 @@ Python list: [3, 4, 1, 2]
 We have just seen the functions [`pylist`](@ref) (for constructing a Python list) and
 [`pyslice`](@ref) (for constructing a Python slice). There are many such functions,
 mirroring most of the Python builtin functions and types. The
-[API Reference](@ref PythonCall API Reference) documents them all.
+[API Reference](@ref py-reference) documents them all.
 
 Most of these functions are essentially Python builtins with a `py` prefix. For example
 `pyint(x)` converts `x` to a Python `int` and is equivalent to `int(x)` in Python when `x`
@@ -132,10 +132,10 @@ In the above example, we converted a Python list to a Julia vector in three ways
 See [here](@ref py2jl) for the rules regarding how `pyconvert(T, x)` works. If `x` is an
 immutable scalar type (such as an `int` or `str`) then `pyconvert(Any, x)` may return the
 corresponding Julia object (such as an `Integer` or `String`). Otherwise it will typically
-return either a [wrapper type](@ref Wrapper types) (such as `PyList{Py}` in the above
+return either a [wrapper type](@ref py-wrappers) (such as `PyList{Py}` in the above
 example) or will fall back to returning a [`Py`](@ref).
 
-## Wrapper types
+## [Wrapper types](@id py-wrappers)
 
 A wrapper is a type which wraps a Python object but provides it with the semantics of some
 other Julia type.

src/Py.jl

@@ -30,7 +30,7 @@ getptr(x) = ispy(x) ? getptr(Py(x)::Py) : throw(MethodError(getptr, (x,)))
 
 Convert `x` to a Python object, of type `Py`.
 
-Conversion happens according to [`these rules`](@ref jl2py-conversion).
+Conversion happens according to [these rules](@ref jl2py-conversion).
 
 Such an object supports attribute access (`obj.attr`), indexing (`obj[idx]`), calling
 (`obj(arg1, arg2)`), iteration (`for x in obj`), arithmetic (`obj + obj2`) and comparison