Add docs/ directory and move api/ there.

Add build instructions doc.
monkz007 · Jun 20, 2016 · 169a1b2 · 169a1b2
1 parent ef401b3
commit 169a1b2
Show file tree

Hide file tree

Showing 38 changed files with 136 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![](https://img.shields.io/badge/pypi-v31.2-blue.png "PyPI latest release")](https://pypi.python.org/pypi/cefpython3/)
 [![](https://img.shields.io/badge/commits%20since-v31.2-lightgray.png "Commits since v31.2 release")](https://github.com/cztomczak/cefpython/compare/05366f2...master)
 
-__NOTES__: 
+__NOTES__:
 * Repository rewritten on 2016-02-15 to reduce its size.
   Please clone it again.
 * Master branch is a work in progress. When building use the cefpython31
@@ -23,10 +23,10 @@ Table of contents:
 
 CEF Python is an open source project founded by [Czarek Tomczak](http://www.linkedin.com/in/czarektomczak) in 2012 to provide python bindings for the [Chromium Embedded Framework](https://bitbucket.org/chromiumembedded/cef). See the growing list of [applications using CEF](http://en.wikipedia.org/wiki/Chromium_Embedded_Framework#Applications_using_CEF) on wikipedia. Examples of embedding CEF browser are available for many popular GUI toolkits including: [wxPython](../../wiki/wxPython), [PyGTK](../../wiki/PyGTK), [PyQt](../../wiki/PyQt), [PySide](../../wiki/PySide), [Kivy](../../wiki/Kivy), [Panda3D](../../wiki/Panda3D) and [PyWin32](src/windows/binaries_32bit/pywin32.py).
 
-Some use cases for CEF: 
+Some use cases for CEF:
 
 * Embed a web browser control with great HTML5 support (based on Chromium)
-* Use it to create a HTML5 based GUI in an application. This can act as a replacement for GUI toolkits like wxWidgets/Qt/Gtk. For native communication between javascript and python use [javascript bindings](../../wiki/JavascriptBindings). Another option is to run an internal python web server and use websockets/XMLHttpRequest for js&lt;&gt;python communication. This way you can write a desktop app in the same way you write web apps. 
+* Use it to create a HTML5 based GUI in an application. This can act as a replacement for GUI toolkits like wxWidgets/Qt/Gtk. For native communication between javascript and python use [javascript bindings](../../wiki/JavascriptBindings). Another option is to run an internal python web server and use websockets/XMLHttpRequest for js&lt;&gt;python communication. This way you can write a desktop app in the same way you write web apps.
 * Render web content off-screen in applications that use custom drawing frameworks. See the [Kivy](../../wiki/Kivy) and [Panda3D](../../wiki/Panda3D) examples.
 * Use it for automated testing of existing web applications. Use it for web scraping, or as a web crawler or other kind of internet bots.
 
@@ -46,13 +46,13 @@ On Win/Mac you can install from PyPI using this command:
 * For Linux: see the [Download_CEF3_Linux](../../wiki/Download_CEF3_Linux) wiki page.
 * For Mac: see the [Download_CEF3_Mac](../../wiki/Download_CEF3_Mac) wiki page.
 
-__New releases RSS/Atom feed__  
+__New releases RSS/Atom feed__
 To be notified of new releases subscribe to this [Atom feed](https://github.com/cztomczak/cefpython/releases.atom).
 
 ## Support
 
-* API docs are in the [api/](api/) directory
-* See [Wiki Pages](../../wiki)
+* API docs are in the [docs/api/](docs/api/) directory
+* See also [Wiki Pages](../../wiki)
 * Ask questions and report problems on the
   [Forum](https://groups.google.com/group/cefpython)
 * Please do not ask questions in the Issue Tracker

diff --git a/docs/Build-instructions.md b/docs/Build-instructions.md
@@ -0,0 +1,122 @@
+# Build instructions
+
+There are two types of builds you can perform. You can build
+PyCEF using the prebuilt CEF binaries. Or you can build both
+PyCEF and CEF from sources. Building CEF is a long process that
+can take hours. In the tools/ directory there is the automate.py
+script that automates building. However before you can run it
+you must satisfy some requirements.
+
+
+Table of contents:
+* [Requirements](#requirements)
+* [Build PyCEF using prebuilt CEF binaries](#build-pycef-using-prebuilt-cef-binaries)
+* [Build both PyCEF and CEF from sources](#build-both-pycef-and-cef-from-sources)
+* [Build CEF manually](#build-cef-manually)
+* [How to patch](#how-to-patch)
+* [Ninja build slows down computer](#ninja-build-slows-down-computer)
+
+
+## Requirements
+
+Below are platform specific requirements. Do these first before
+following instructions in the "All platforms" section that lists
+requirements common for all platforms.
+
+__Windows__
+
+* For Python 2.7 - VS2008 compiler is required:
+  http://www.microsoft.com/en-us/download/details.aspx?id=44266
+* For Python 3.4 - VS2010 compiler is required:
+  https://docs.python.org/3.4/using/windows.html#compiling-python-on-windows
+* For Python 3.5 - VS2015 compiler is required:
+  https://docs.python.org/3.5/using/windows.html#compiling-python-on-windows
+* To build CEF from sources:
+    * Use Win7 x64 or later. 32-bit OS'es are not supported. For more details see [here]
+    (https://www.chromium.org/developers/how-tos/build-instructions-windows).
+    * For CEF branch >= 2704 install VS2015 Update 2 or later
+    * For CEF branch < 2704 install VS2013 Update 4 or later
+    * Install [CMake](https://cmake.org/) 2.8.12.1 or newer and add cmake.exe
+        to PATH
+    * Install [ninja](http://martine.github.io/ninja/) and add ninja.exe
+        to PATH
+    * You need about 16 GB of RAM during linking. If there is an error
+        just add additional virtual memory.
+    * For Python 2.7 copy "pycef/src/windows/stdint.h" to
+      "%LocalAppData%\Programs\Common\Microsoft\Visual C++ for Python\9.0\VC\include\"
+
+__All platforms__
+
+* Install dependencies for the automate.py tool by executing:
+  `cd tools/ && pip install -r requirements.txt`. This will install
+  some PyPI packages including Cython. On Windows installing Cython
+  requires a VS compiler - see instructions above for Windows.
+
+
+## Build PyCEF using prebuilt CEF binaries
+
+Run the automate.py tool using the --prebuilt-cef flag:
+```
+cd tools/
+python automate.py --prebuilt-cef
+```
+
+You should be fine by running it with the default options, but if you
+need to customize the build then use the --help flag to see more.
+
+
+## Build both PyCEF and CEF from sources
+
+Run the automate.py tool using the --build-cef flag:
+```
+cd tools/
+python automate.py --build-cef --cef-branch 2526
+```
+
+You should be fine by running it with the default options, but if you
+need to customize the build then use the --help flag to see more.
+
+
+## Build CEF manually
+
+CEF Python official binaries come with custom CEF binaries with
+a few patches applied for our use case. These patches are in the
+patches/ directory.
+
+On Linux before running any of CEF tools apply the issue73 patch
+first.
+
+To build CEF follow the instructions on the Branches and
+Building CEF wiki page:
+https://bitbucket.org/chromiumembedded/cef/wiki/BranchesAndBuilding
+
+After it is successfully built - apply patches, rebuild and remake
+distribs.
+
+Note that CEF patches must be applied in the "download_dir/chromium/src/cef/"
+directory, not in the "download_dir/cef/" directory.
+
+
+## How to patch
+
+Create a patch from unstaged changes in current directory:
+```
+cd chromium/src/cef/
+git diff --no-prefix --relative > cef.gyp.patch
+```
+
+Apply a patch in current directory:
+```
+cd chromium/src/cef/
+git apply cef.gyp.patch
+```
+
+
+## Ninja build slows down computer
+
+If ninja slows down your computer too much (6 parallel jobs by default),
+build manually with this command (where -j2 means to run 2 jobs in parallel):
+```
+cd chromium/src
+ninja -v -j2 -Cout\Release cefclient
+```
diff --git a/api/API-categories.md → docs/api/API-categories.md b/api/API-categories.md → docs/api/API-categories.md
diff --git a/api/API-index.md → docs/api/API-index.md b/api/API-index.md → docs/api/API-index.md
diff --git a/api/ApplicationSettings.md → docs/api/ApplicationSettings.md b/api/ApplicationSettings.md → docs/api/ApplicationSettings.md
diff --git a/api/Browser.md → docs/api/Browser.md b/api/Browser.md → docs/api/Browser.md
diff --git a/api/BrowserSettings.md → docs/api/BrowserSettings.md b/api/BrowserSettings.md → docs/api/BrowserSettings.md
diff --git a/api/Callback.md → docs/api/Callback.md b/api/Callback.md → docs/api/Callback.md
diff --git a/api/CommandLineSwitches.md → docs/api/CommandLineSwitches.md b/api/CommandLineSwitches.md → docs/api/CommandLineSwitches.md
diff --git a/api/Cookie.md → docs/api/Cookie.md b/api/Cookie.md → docs/api/Cookie.md
diff --git a/api/CookieManager.md → docs/api/CookieManager.md b/api/CookieManager.md → docs/api/CookieManager.md
diff --git a/api/CookieVisitor.md → docs/api/CookieVisitor.md b/api/CookieVisitor.md → docs/api/CookieVisitor.md
diff --git a/api/DisplayHandler.md → docs/api/DisplayHandler.md b/api/DisplayHandler.md → docs/api/DisplayHandler.md
diff --git a/api/DownloadHandler.md → docs/api/DownloadHandler.md b/api/DownloadHandler.md → docs/api/DownloadHandler.md
diff --git a/api/DpiAware.md → docs/api/DpiAware.md b/api/DpiAware.md → docs/api/DpiAware.md
diff --git a/api/Frame.md → docs/api/Frame.md b/api/Frame.md → docs/api/Frame.md
diff --git a/api/JavascriptBindings.md → docs/api/JavascriptBindings.md b/api/JavascriptBindings.md → docs/api/JavascriptBindings.md
diff --git a/api/JavascriptCallback.md → docs/api/JavascriptCallback.md b/api/JavascriptCallback.md → docs/api/JavascriptCallback.md
diff --git a/api/JavascriptContextHandler.md → docs/api/JavascriptContextHandler.md b/api/JavascriptContextHandler.md → docs/api/JavascriptContextHandler.md
@@ -24,6 +24,8 @@ Table of contents:
 
 Called shortly after (process message delay) the V8 context for a frame has been created.
 
+If the page does not contain `<script>` tags then this method won't get called.
+
 
 ### OnContextReleased
 

diff --git a/api/JavascriptDialogHandler.md → docs/api/JavascriptDialogHandler.md b/api/JavascriptDialogHandler.md → docs/api/JavascriptDialogHandler.md
diff --git a/api/KeyboardHandler.md → docs/api/KeyboardHandler.md b/api/KeyboardHandler.md → docs/api/KeyboardHandler.md
diff --git a/api/LifespanHandler.md → docs/api/LifespanHandler.md b/api/LifespanHandler.md → docs/api/LifespanHandler.md
diff --git a/api/LoadHandler.md → docs/api/LoadHandler.md b/api/LoadHandler.md → docs/api/LoadHandler.md
diff --git a/api/NetworkError.md → docs/api/NetworkError.md b/api/NetworkError.md → docs/api/NetworkError.md
diff --git a/api/PaintBuffer.md → docs/api/PaintBuffer.md b/api/PaintBuffer.md → docs/api/PaintBuffer.md
diff --git a/api/RenderHandler.md → docs/api/RenderHandler.md b/api/RenderHandler.md → docs/api/RenderHandler.md
diff --git a/api/Request.md → docs/api/Request.md b/api/Request.md → docs/api/Request.md
@@ -93,7 +93,7 @@ Set the request method type.
 
 | | |
 | --- | --- |
-| __Return__ | list|dict |
+| __Return__ | list/dict |
 
 Get the post data. If the form content type is "multipart/form-data"
 then the post data will be returned as a list. If the form content
@@ -105,7 +105,7 @@ be returned as a dict.
 
 | Parameter | Type |
 | --- | --- |
-| postData | list|dict |
+| postData | list/dict |
 | __Return__ | void |
 
 Set the post data. See GetPostData() for an explanation of the
@@ -186,7 +186,7 @@ Set the flags used in combination with [WebRequest](WebRequest.md).
 | --- | --- |
 | __Return__ | str |
 
-Get the url to the first party for cookies used in combination with  
+Get the url to the first party for cookies used in combination with
 WebRequest.
 
 
@@ -197,7 +197,7 @@ WebRequest.
 | url | string |
 | __Return__ | void |
 
-Set the url to the first party for cookies used in combination with  
+Set the url to the first party for cookies used in combination with
 WebRequest.
 
 
@@ -220,7 +220,7 @@ Get the resource type for this request. Accurate resource type information may o
 
 Not yet implemented in CEF Python.
 
-Get the transition type for this request. Only available in the browser  
-process and only applies to requests that represent a main frame or  
+Get the transition type for this request. Only available in the browser
+process and only applies to requests that represent a main frame or
 sub-frame navigation.
 
diff --git a/api/RequestHandler.md → docs/api/RequestHandler.md b/api/RequestHandler.md → docs/api/RequestHandler.md
diff --git a/api/ResourceHandler.md → docs/api/ResourceHandler.md b/api/ResourceHandler.md → docs/api/ResourceHandler.md
diff --git a/api/Response.md → docs/api/Response.md b/api/Response.md → docs/api/Response.md
diff --git a/api/StringVisitor.md → docs/api/StringVisitor.md b/api/StringVisitor.md → docs/api/StringVisitor.md
diff --git a/api/VirtualKey.md → docs/api/VirtualKey.md b/api/VirtualKey.md → docs/api/VirtualKey.md
diff --git a/api/WebPluginInfo.md → docs/api/WebPluginInfo.md b/api/WebPluginInfo.md → docs/api/WebPluginInfo.md
diff --git a/api/WebRequest.md → docs/api/WebRequest.md b/api/WebRequest.md → docs/api/WebRequest.md
diff --git a/api/WebRequestClient.md → docs/api/WebRequestClient.md b/api/WebRequestClient.md → docs/api/WebRequestClient.md
diff --git a/api/WindowInfo.md → docs/api/WindowInfo.md b/api/WindowInfo.md → docs/api/WindowInfo.md
diff --git a/api/WindowUtils.md → docs/api/WindowUtils.md b/api/WindowUtils.md → docs/api/WindowUtils.md
diff --git a/api/cefpython.md → docs/api/cefpython.md b/api/cefpython.md → docs/api/cefpython.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,6 +24,8 @@ Table of contents:

		Called shortly after (process message delay) the V8 context for a frame has been created.

		If the page does not contain `<script>` tags then this method won't get called.


		### OnContextReleased

Expand Down