Update documentation

README.md

@@ -1,125 +1,30 @@
 # Skia python binding
+
 Python binding to [Skia Graphics Library](https://skia.org/).
 
 - Binding based on [pybind11](https://github.com/pybind/pybind11).
 
-## Installation
-
-First, clone the repo.
-
-```bash
-git clone --recursive https://github.com/kyamagu/skia-python.git
-cd skia-python
-```
-
-### Linux
-
-Prerequisites:
-
-- Python 2.7 (build time only)
-- GLIBC >= 2.17
-- fontconfig >= 2.10.93
-- OpenGL
-
-
-Install dependencies:
-
-```bash
-apt-get install -y libfontconfig1-dev libgl-dev libgl1-mesa-dri
-```
-
-or,
-
-```bash
-yum install -y fontconfig-devel mesa-libGL-devel mesa-dri-drivers
-```
-
-Set up `PATH` to the `depot_tools`. Note the build tools require relatively new
-glibc and python 2.7.
-
-```bash
-export PATH="$PWD/depot_tools:$PATH"
-```
-
-Then, build skia library. At this point, `python` executable should be python 2.
-
-```bash
-cd skia
-python2 tools/git-sync-deps
-bin/gn gen out/Release --args='is_official_build=false is_debug=false extra_cflags_cc=["-frtti"] extra_ldflags=["-lrt"]'
-ninja -C out/Release skia skia.h
-cd ..
-```
+Supported platforms:
 
-For detailed Skia build instructions, check [the official page](https://skia.org/).
+- Linux x86_64
+- macOS
+- Windows x86_64
 
-Finally, build and install skia python binding. At this point, `python` should
-be set to the desired version.
+Currently, the binding is in under active development.
 
-```bash
-export SKIA_PATH=$PWD/skia
-python -m pip install pybind11 numpy
-python setup.py install
-```
+## Examples
 
-### macOS
-
-Set up `PATH` to the `depot_tools`.
-
-```bash
-export PATH="$PWD/depot_tools:$PATH"
-```
-
-Then, build skia library. At this point, `python` executable should be python 2.
-
-```bash
-cd skia
-python2 tools/git-sync-deps
-bin/gn gen out/Release --args='is_official_build=false is_debug=false extra_cflags_cc=["-frtti"]'
-ninja -C out/Release skia skia.h
-cd ..
-```
-
-For detailed Skia build instructions, check [the official page](https://skia.org/).
-
-Finally, build and install skia python binding. At this point, `python` should
-be set to the desired version.
-
-```bash
-export SKIA_PATH=$PWD/skia
-python -m pip install pybind11 numpy
-python setup.py install
-```
-
-### Windows
-
-Windows binary can be built using the generic steps above. However, Windows
-support is experimental.
-
-
-## Testing
-
-```bash
-python -m pip install pytest numpy glfw
-python -m pytest tests
-```
-
-Alternatively, use `tox` to run tests under various python versions.
-
-```bash
-export SKIA_PATH=$PWD/skia
-tox
-```
+- [Canvas Overview](tree/master/notebooks/Canvas-Overview.ipynb)
+- [Canvas Creation](tree/master/notebooks/Canvas-Creation.ipynb)
+- [Path Overview](tree/master/notebooks/Path-Overview.ipynb)
 
 ## Documentation
 
-Once skia-python is installed, sphinx documentation can be built:
-
-```
-python -m pip install sphinx
-make -C docs html
-```
+https://kyamagu.github.io/skia-python
 
+- [Build instruction](https://kyamagu.github.io/skia-python/build.html)
+- [Usage](https://kyamagu.github.io/skia-python/reference.html)
+- [Reference](https://kyamagu.github.io/skia-python/reference.html)
 
 ## Contributing
 

docs/build.rst

@@ -0,0 +1,154 @@
+Build instruction
+=================
+
+First, clone the repo.
+
+.. code-block:: bash
+
+    git clone --recursive https://github.com/kyamagu/skia-python.git
+    cd skia-python
+
+The repository bundles `skia` and its build tools (`depot_tools`) as submodules.
+`skia` must be built first to build Python binding.
+
+For building skia, there are a few compile-time requirements:
+
+- Run-time type information (RTTI) must be enabled.
+
+  - ``-frtti`` flag for ``clang`` or ``gcc``
+  - ``/GR`` flag for ``cl.exe`` (Visual C++)
+
+- ``gn`` args should include ``skia_enable_tools = true`` to build ``skia.h`` header.
+  This is automatically enabled when ``is_official_build = false``.
+- Static linking is assumed; therefore, ``is_component_build = false``.
+
+For detailed Skia build instructions, check `the official page`_.
+
+.. _the official page: https://skia.org/
+
+Linux
+-----
+
+Prerequisites:
+
+- Python 2.7 (build time only)
+- GLIBC >= 2.17
+- fontconfig >= 2.10.93
+- OpenGL
+
+
+Install dependencies:
+
+.. code-block:: bash
+
+    apt-get install -y libfontconfig1-dev libgl-dev libgl1-mesa-dri
+
+or:
+
+.. code-block:: bash
+
+    yum install -y fontconfig-devel mesa-libGL-devel mesa-dri-drivers
+
+
+Set up ``PATH`` to the ``depot_tools``. build skia library. At this point,
+``python`` executable should be python 2. Note the build tools require
+relatively new glibc and python 2.7.
+
+.. code-block:: bash
+
+    export PATH="$PWD/depot_tools:$PATH"
+    cd skia
+    python2 tools/git-sync-deps
+    bin/gn gen out/Release --args='is_official_build=true skia_enable_tools=true skia_use_system_libjpeg_turbo=false skia_use_system_libwebp=false skia_use_system_libpng=false skia_use_system_icu=false skia_use_system_harfbuzz=false extra_cflags_cc=["-frtti"] extra_ldflags=["-lrt"]'
+    ninja -C out/Release skia skia.h
+    cd ..
+
+Then, build the skia python binding. At this point, ``python`` should be set to
+the desired version.
+
+.. code-block:: bash
+
+    export SKIA_PATH=$PWD/skia
+    export SKIA_OUT_PATH=$SKIA_PATH/out/Release
+    python -m pip install pybind11 numpy wheel
+    python setup.py bdist_wheel
+
+macOS
+-----
+
+Prerequisites:
+
+- Python 2.7 (build time only)
+- Xcode Command Line Tools
+
+Set up ``PATH`` to the ``depot_tools``, and build skia library. At this point,
+``python`` executable should be python 2.
+
+.. code-block:: bash
+
+    export PATH="$PWD/depot_tools:$PATH"
+    cd skia
+    python2 tools/git-sync-deps
+    bin/gn gen out/Release --args='is_official_build=true skia_enable_tools=true skia_use_system_libjpeg_turbo=false skia_use_system_libwebp=false skia_use_system_libpng=false skia_use_system_icu=false skia_use_system_harfbuzz=false extra_cflags_cc=["-frtti"]'
+    ninja -C out/Release skia skia.h
+    cd ..
+
+Then, build the skia python binding. At this point, ``python`` should be set to
+the desired version.
+
+.. code-block:: bash
+
+    export SKIA_PATH=$PWD/skia
+    export SKIA_OUT_PATH=$SKIA_PATH/out/Release
+    python -m pip install pybind11 numpy wheel
+    python setup.py bdist_wheel
+
+Windows
+-------
+
+Prerequisites:
+
+- Python 2.7 (build time only)
+- Visual C++ version that supports C++14
+
+Windows binary can be built using the generic steps above.
+
+.. code-block:: powershell
+
+    $env:Path += ";$pwd\depot_tools"
+
+    cd skia
+    python2 tools\git-sync-deps
+    bin\gn gen out\Release --args='is_official_build=true skia_enable_tools=true skia_use_system_libjpeg_turbo=false skia_use_system_libwebp=false skia_use_system_libpng=false skia_use_system_icu=false skia_use_system_harfbuzz=false skia_use_system_expat=false skia_use_system_zlib=false extra_cflags_cc=[\"/GR\", \"/EHsc\"] target_cpu=\"${{ matrix.arch }}\"'
+    ninja -C out\Release skia skia.h
+    cd ..
+
+    python -m pip install pybind11 numpy wheel
+    python setup.py bdist_wheel
+
+Testing
+-------
+
+.. code-block:: bash
+
+    python -m pip install pytest numpy glfw
+    python -m pytest tests
+
+Alternatively, use ``tox`` to run tests under various python versions.
+
+.. code-block:: bash
+
+    export SKIA_PATH=$PWD/skia
+    export SKIA_OUT_PATH=$SKIA_PATH/out/Release
+    tox
+
+
+Building documentation
+----------------------
+
+Once skia-python is installed, sphinx documentation can be built:
+
+.. code-block:: bash
+
+    python -m pip install sphinx
+    make -C docs html

docs/index.rst

@@ -1,14 +1,32 @@
-skia-python documentation
-=========================
+skia-python
+===========
 
+`skia-python` is a Python binding to `Skia Graphics Library`_.
 
-API Reference
+Skia is an open source 2D graphics library which provides common APIs that work
+across a variety of hardware and software platforms.
+
+`skia-python` is developed at `Github`_.
+
+.. _Skia Graphics Library: https://skia.org/
+
+.. _Github: https://github.com/kyamagu/skia-python
+
+Supported platforms:
+
+- Linux x86_64
+- macOS
+- Windows x86_64
+
+Documentation
 -------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   skia
+   build
+   usage
+   reference
 
 Indices and tables
 ------------------

docs/skia.rst → docs/reference.rst

@@ -1 +1,4 @@
+Reference
+---------
+
 .. automodule:: skia