Merge pull request #4 from sinhrks/add_doc2

DOC: Add doc descriptions

README.rst

@@ -1,12 +1,12 @@
 cesiumpy
 ========
 
-Lightweight Python wrapper for `Cesium.js <http://cesiumjs.org/>`_ Mainly intended to be used with ``Jupyter`` Notebook.
+Lightweight Python wrapper for `Cesium.js <http://cesiumjs.org/>`_. Mainly intended to be used with ``Jupyter Notebook``.
 
 Example
-=======
+-------
 
-Running following script on ``Jupyter`` Notebook will show the embedded interactive 3D map.
+Running following script on ``Jupyter`` Notebook will show an embedded interactive 3D map.
 
 .. code-block:: python
 
@@ -18,3 +18,5 @@ Running following script on ``Jupyter`` Notebook will show the embedded interact
   >>> v
 
 .. image:: https://raw.githubusercontent.com/sinhrks/cesiumpy/master/doc/source/_static/main.png
+
+

doc/source/basics.rst

@@ -1,10 +1,21 @@
 Basics
 ======
 
+This section describes the basic usage of ``cesiumpy``. ``cesiumpy`` is the lightweight
+wrapper for `Cesium.js <http://cesiumjs.org/>`_.
+
+This package offers limited API intended for:
+
+- Interactive data visualization using ``Jupyter Notebook``
+
+This package DOES NOT intended for:
+
+- Website development using whole functionality of `Cesium.js <http://cesiumjs.org/>`_.
+
 Installation
 ------------
 
-Use ``pip``
+Use ``pip``.
 
 .. code-block:: sh
 
@@ -15,8 +26,10 @@ Display Cesium Widget
 ---------------------
 
 The easiest way to show the ``Cesium`` on your browser is to use ``CesiumWidget`` on
-``Jupyter Notebook``.  Because ``CesiumWidget`` has ``_repr_html_`` method to render
-``HTML`` on ``Jupyter Notebook``, the ``Cesium`` will be implemented on the output cell.
+``Jupyter Notebook``.
+
+Because ``CesiumWidget`` has ``_repr_html_`` method to render ``HTML`` on ``Jupyter Notebook``,
+placing variable contains ``CesiumWidget`` will output the map implemented on the output cell.
 
 .. code-block:: python
 
@@ -27,7 +40,7 @@ The easiest way to show the ``Cesium`` on your browser is to use ``CesiumWidget`
 
 .. image:: ./_static/main.png
 
-If you do not use ``Jupyter Notebook``, you can use ``.to_html`` method to output ``HTML``.
+If you do not use ``Jupyter Notebook``, you can use ``.to_html`` method to output rendered ``HTML``.
 Save the output as a file then open with your web browser.
 
 .. code-block:: python
@@ -39,8 +52,7 @@ Save the output as a file then open with your web browser.
 Add Entities
 ------------
 
-``Cesium`` allows you to add various entities on the map. To do this, create ``Viewer`` instance and
-add preferable entity.
+`Cesium.js <http://cesiumjs.org/>`_ allows you to add various entities on the map. To do this, create ``Viewer`` instance and add preferable entity.
 
 Even though ``Viewer`` also has various type of user control menus, below example disable almost of them because some of them are not displayed on ``Jupyter Notebook`` properly.
 
@@ -58,6 +70,25 @@ Even though ``Viewer`` also has various type of user control menus, below exampl
 
 .. image:: ./_static/viewer01.png
 
+Refer to following document to see the whole list of `Cesium.js <http://cesiumjs.org/>`_ entities:
+
+- http://cesiumjs.org/tutorials/Visualizing-Spatial-Data/
+
+``cesiumpy`` currently supports following entities. Refer to ``cesiumpy`` API document for more details.
+
+- ``Box``
+- ``Ellipse``
+- ``Cylinder``
+- ``Polygon``
+- ``Rectangle``
+- ``Ellipsoid``
+- ``Wall``
+- ``Corridor``
+- ``Polyline``
+- ``PolylineVolume``
+
+The below example draws all entities on the map.
+
 .. code-block:: python
 
   >>> v = cesiumpy.Viewer(**options)
@@ -112,14 +143,21 @@ Even though ``Viewer`` also has various type of user control menus, below exampl
 Add Providers
 -------------
 
-``Cesium`` has 2 types of providers:
+`Cesium.js <http://cesiumjs.org/>`_ supports some "layers" to cover the map. Objects which provides "layers" are called as "provider". There are 2 types of providers as below:
 
-* ``ImageryProvider``
-* ``TerrainProvider``
+* ``ImageryProvider``: Provides layers with imagery
+* ``TerrainProvider``: Provides layers with terrain and water effects
 
 ImageryProvider
 ^^^^^^^^^^^^^^^
 
+Refer to following document for the general explanation of ``ImageryProvider``:
+
+- http://cesiumjs.org/tutorials/Imagery-Layers-Tutorial/
+
+The below example outputs the map covered by the image provided by the ArcGIS MapServer,
+as the same as the above tutorial.
+
 .. code-block:: python
 
   >>> url = 'http://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer'
@@ -131,6 +169,8 @@ ImageryProvider
 .. image:: ./_static/imagery01.png
 
 
+Also you can use other providers.
+
 .. code-block:: python
 
   >>> url = '//cesiumjs.org/tilesets/imagery/blackmarble'
@@ -145,17 +185,25 @@ ImageryProvider
 TerrainProvider
 ^^^^^^^^^^^^^^^
 
+Refer to following document for the general explanation of ``TerrainProvider``:
+
+- http://cesiumjs.org/tutorials/Terrain-Tutorial/
+
+The below example outputs the map covered by the terrain provided by the Cesium Terrain Server,
+as the same as the above tutorial.
+
 .. code-block:: python
 
   >>> url = '//assets.agi.com/stk-terrain/world'
   >>> terrainProvider = cesiumpy.CesiumTerrainProvider(url=url)
   >>> v = cesiumpy.Viewer(terrainProvider=terrainProvider, **options)
   >>> v
 
-
 .. image:: ./_static/terrain01.png
 
 
+Passing ``requestWaterMask=True`` enables water effects.
+
 .. code-block:: python
 
   >>> terrainProvider = cesiumpy.CesiumTerrainProvider(url=url, requestWaterMask=True)

doc/source/examples.rst

@@ -1,9 +1,21 @@
 Examples
 ========
 
+This section lists some examples using ``cesiumpy`` and other packages. You
+can find ``Jupyter Notebook`` of these exampless under ``GitHub`` repository
+(maps are not rendered on ``GitHub``. Download an run them on local).
+
+- https://github.com/sinhrks/cesiumpy/tree/master/examples
+
 Use with pandas
 ---------------
 
+Following example shows retrieving ``US National Parks`` data from Wikipedia,
+then plot number of visitors on the map.
+
+First, load data from Wikipedia using ``pd.read_html`` functionality. The data
+contains latitude and longtitude as text, thus some preprocessing is required.
+
 .. code-block:: python
 
   >>> import pandas as pd
@@ -31,6 +43,11 @@ Use with pandas
 
   >>> df = pd.concat([df, locations], axis=1)
 
+Once prepared the data, iterate over rows and plot its values. The below script adds
+``cesiumpy.Cylinder`` which height is corresponding to the number of visitors.
+
+.. code-block:: python
+
   >>> import cesiumpy
 
   >>> options = dict(animation=True, baseLayerPicker=False, fullscreenButton=False,
@@ -54,6 +71,11 @@ Use with pandas
 Use with shapely / geopandas
 ----------------------------
 
+Following example shows how to handle ``geojson`` files using ``cesiumpy``.
+
+First, read ``geojson`` file of US, California using ``geopandas`` function.
+The content will be ``shapely`` instance.
+
 .. code-block:: python
 
   >>> import geopandas as gpd
@@ -67,6 +89,12 @@ Use with shapely / geopandas
   >>> type(g)
   shapely.geometry.polygon.Polygon
 
+
+We can use this ``shapely`` instance to specify the shape of ``cesiumpy`` instances.
+The below script adds ``cesiumpy.Wall`` which has the shape of California.
+
+.. code-block:: python
+
   >>> import cesiumpy
 
   >>> options = dict(animation=True, baseLayerPicker=False, fullscreenButton=False,