diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..acd69fc --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,23 @@ +# Makefile for Sphinx documentation + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -m sphinx +SOURCEDIR = source +BUILDDIR = build + +.PHONY: help clean html + +help: + @echo "Please use 'make ' where is one of" + @echo " clean to clear all built documentation files" + @echo " html to make all standalone HTML files" + +clean: + -rm -rf $(BUILDDIR)/* + +html: clean + sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/html + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..92fc0cc --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,39 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. clean to clear all built documentation files + echo. html to make all standalone HTML files + + goto end +) + +if "%1" == "clean" ( + rmdir %BUILDDIR% /s /q + goto end +) + +if "%1" == "html" ( + sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html + %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +:end diff --git a/docs/source/.gitignore b/docs/source/.gitignore new file mode 100644 index 0000000..9400b55 --- /dev/null +++ b/docs/source/.gitignore @@ -0,0 +1 @@ +_autosummary/ \ No newline at end of file diff --git a/docs/source/_static/css/styles.css b/docs/source/_static/css/styles.css new file mode 100644 index 0000000..f8a5315 --- /dev/null +++ b/docs/source/_static/css/styles.css @@ -0,0 +1,96 @@ +/* +Logo +==== +*/ + +.logo { + max-height: 200px; +} + +/* +Header +====== +*/ + +#navbar-main { + background-color: #F1F1F1!important; + border-bottom: 3px solid #16255F; + height: 70px; +} + +.navbar-brand { + padding: 0.25rem; +} + + +/* +Body +==== +*/ + +body { + background-color: #FAFAFA!important; + color: #353D46!important; +} + + +/* +Left side bar +============= +*/ + +.form-control { + background-color: #FAFAFA!important; +} + +[type=search] { + background-color: #FAFAFA; +} + + +/* +Headings +======== +*/ + +h1, +h2, +h3, +h4, +h5, +h6 { + color: #062161!important; +} + +/* +Releases dropdown +======== +*/ + +li.dropdown { + margin-right: auto; +} + +.dropdown { + list-style: none; +} + +.dropdown > a:hover { + COLOR: #00194f; + TEXT-DECORATION: none; + font-weight: none; +} + +div.rst-versions { + overflow: hidden!important; +} + +.deprecated-warning { + font-family: sans-serif; + font-weight:bold; + text-align: center; + background-color: pink; + color: firebrick; + right:0em; + z-index:1000000000000; +} \ No newline at end of file diff --git a/docs/source/_static/img/favicon.ico b/docs/source/_static/img/favicon.ico new file mode 100644 index 0000000..27c91a3 Binary files /dev/null and b/docs/source/_static/img/favicon.ico differ diff --git a/docs/source/_static/img/logo.png b/docs/source/_static/img/logo.png new file mode 100644 index 0000000..8ba5296 Binary files /dev/null and b/docs/source/_static/img/logo.png differ diff --git a/docs/source/_static/img/logo.svg b/docs/source/_static/img/logo.svg new file mode 100644 index 0000000..68359a2 --- /dev/null +++ b/docs/source/_static/img/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/_templates/docs-navbar.html b/docs/source/_templates/docs-navbar.html new file mode 100644 index 0000000..34801e4 --- /dev/null +++ b/docs/source/_templates/docs-navbar.html @@ -0,0 +1,56 @@ +
+ + + {% if logo %} + {% if not theme_logo_link %} + + + + {% elif theme_logo_link[:4] == 'http' %} + + + + {% else %} + + + + {% endif %} + {% else %} + +

{{ project }}

+ + {% endif %} +
  • + + +
    • + + + {% set navbar_class, navbar_align = navbar_align_class() %} + +
    \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..4fdc072 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,92 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import json +import sys +sys.path.insert(0, os.path.abspath('../..')) + + +# -- Project information ----------------------------------------------------- + +project = 'mapshader' +copyright = '2021, makepath' +author = 'makepath' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + 'sphinx_multiversion', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'pydata_sphinx_theme' + +html_logo = '_static/img/logo.svg' + +html_favicon = '_static/img/favicon.ico' + +# sphinx-multiversion config +smv_branch_whitelist = 'master' + +smv_tag_whitelist = r'^v([0-9]\.[1]\.[3-9]|[1-9]\.[0-9]\.[0-9])' + +# Load releases +with open('releases.json') as f: + releases = json.load(f) + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + 'external_links': [], + 'github_url': 'https://github.com/makepath/mapshader', +} + +html_context = { + 'css_files': ['_static/css/styles.css'], + 'releases': [(release, url) for release, url in releases.items()], +} + +autosummary_generate = True + +exclude_patterns = ['_build', '_templates'] + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# autodoc config +autodoc_mock_imports = ['mapshader.colors'] diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst new file mode 100644 index 0000000..15cddc5 --- /dev/null +++ b/docs/source/getting_started/index.rst @@ -0,0 +1,11 @@ +.. _getting_started: + +*************** +Getting started +*************** + +.. toctree:: + :maxdepth: 2 + + installation + usage \ No newline at end of file diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst new file mode 100644 index 0000000..ab95a88 --- /dev/null +++ b/docs/source/getting_started/installation.rst @@ -0,0 +1,22 @@ +.. _getting_started.installation: + +************ +Installation +************ + +.. code-block:: bash + + # via pip + pip install mapshader + + +Setup Mapshader Conda Environment +================================= + +.. code-block:: bash + + conda create -n mapshader python=3.8 + conda activate mapshader + git clone git@github.com:makepath/mapshader.git + cd mapshader + pip install -e . diff --git a/docs/source/getting_started/usage.rst b/docs/source/getting_started/usage.rst new file mode 100644 index 0000000..f1ffd4b --- /dev/null +++ b/docs/source/getting_started/usage.rst @@ -0,0 +1,88 @@ +.. _getting_started.usage: + +***** +Usage +***** + +Run Tests +========= + +.. code-block:: bash + + conda activate mapshader + pytest mapshader/tests -sv + + +Run Flask Server +================ + +.. code-block:: bash + + conda activate mapshader + python mapshader/flask_app.py + + >>> * Serving Flask app "flask_app" (lazy loading) + >>> * Environment: production + >>> WARNING: This is a development server. Do not use it in a production deployment. + >>> Use a production WSGI server instead. + >>> * Debug mode: on + >>> * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit) + >>> * Restarting with stat + + +Mapshader Config (YAML) +======================= + +While mapshader comes with default services to help with testing, users can create their own services via YAML. + +*my_services.yaml* + +.. code-block:: yaml + + --- + + metadata: + version: 1 + + sources: + - name: Elevation + key: elevation-user + text: Elevation + description: Global elevation + geometry_type: raster + shade_how: linear + span: min/max + raster_interpolate: linear + xfield: geometry + yfield: geometry + filepath: ~/mapshader/mapshader/tests/fixtures/elevation.tif + transforms: + - name: squeeze + args: + dim: band + - name: cast + args: + dtype: float64 + - name: orient_array + - name: flip_coords + args: + dim: y + - name: reproject_raster + args: + epsg: 3857 + + +This configuration file can then be passed to the flask server upon startup: + +.. code-block:: bash + + conda activate mapshader + python mapshader/flask_app.py -f my_services.yaml + + >>> * Serving Flask app "flask_app" (lazy loading) + >>> * Environment: production + >>> WARNING: This is a development server. Do not use it in a production deployment. + >>> Use a production WSGI server instead. + >>> * Debug mode: on + >>> * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit) + >>> * Restarting with stat \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..63a40d4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,15 @@ +.. _index: + +*********************** +mapshader documentation +*********************** + +Simple Python GIS Web Services. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + getting_started/index + reference/index \ No newline at end of file diff --git a/docs/source/reference/core.rst b/docs/source/reference/core.rst new file mode 100644 index 0000000..ac818fb --- /dev/null +++ b/docs/source/reference/core.rst @@ -0,0 +1,23 @@ +.. _core: + +**** +Core +**** + +.. autosummary:: + :toctree: _autosummary + + mapshader.core.create_agg + mapshader.core.point_aggregation + mapshader.core.line_aggregation + mapshader.core.polygon_aggregation + mapshader.core.raster_aggregation + mapshader.core.apply_additional_transforms + mapshader.core.shade_discrete + mapshader.core.shade_agg + mapshader.core.to_raster + mapshader.core.render_map + mapshader.core.get_source_data + mapshader.core.get_legend + mapshader.core.render_geojson + mapshader.core.render_legend diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst new file mode 100644 index 0000000..336c11c --- /dev/null +++ b/docs/source/reference/index.rst @@ -0,0 +1,16 @@ +.. _reference: + +********* +Reference +********* + +.. toctree:: + :maxdepth: 2 + + core + io + mercator + services + sources + transforms + \ No newline at end of file diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst new file mode 100644 index 0000000..53bd910 --- /dev/null +++ b/docs/source/reference/io.rst @@ -0,0 +1,11 @@ +.. _io: + +** +IO +** + +.. autosummary:: + :toctree: _autosummary + + mapshader.io.load_raster + mapshader.io.load_vector diff --git a/docs/source/reference/mercator.rst b/docs/source/reference/mercator.rst new file mode 100644 index 0000000..af9bdb3 --- /dev/null +++ b/docs/source/reference/mercator.rst @@ -0,0 +1,10 @@ +.. _mercator: + +******** +Mercator +******** + +.. autosummary:: + :toctree: _autosummary + + mapshader.mercator.MercatorTileDefinition diff --git a/docs/source/reference/services.rst b/docs/source/reference/services.rst new file mode 100644 index 0000000..868d224 --- /dev/null +++ b/docs/source/reference/services.rst @@ -0,0 +1,16 @@ +.. _services: + +******** +Services +******** + +.. autosummary:: + :toctree: _autosummary + + mapshader.services.MapService + mapshader.services.TileService + mapshader.services.ImageService + mapshader.services.WMSService + mapshader.services.GeoJSONService + mapshader.services.parse_sources + mapshader.services.get_services diff --git a/docs/source/reference/sources.rst b/docs/source/reference/sources.rst new file mode 100644 index 0000000..e3757a7 --- /dev/null +++ b/docs/source/reference/sources.rst @@ -0,0 +1,12 @@ +.. _sources: + +******* +Sources +******* + +.. autosummary:: + :toctree: _autosummary + + mapshader.sources.MapSource + mapshader.sources.RasterSource + mapshader.sources.VectorSource diff --git a/docs/source/reference/transforms.rst b/docs/source/reference/transforms.rst new file mode 100644 index 0000000..b3c55ed --- /dev/null +++ b/docs/source/reference/transforms.rst @@ -0,0 +1,25 @@ +.. _transforms: + +********** +Transforms +********** + +.. autosummary:: + :toctree: _autosummary + + mapshader.transforms.reproject_raster + mapshader.transforms.reproject_vector + mapshader.transforms.flip_coords + mapshader.transforms.to_spatialpandas + mapshader.transforms.squeeze + mapshader.transforms.cast + mapshader.transforms.orient_array + mapshader.transforms.get_data_array_extent + mapshader.transforms.canvas_like + mapshader.transforms.build_vector_overviews + mapshader.transforms.build_raster_overviews + mapshader.transforms.add_xy_fields + mapshader.transforms.select_by_attributes + mapshader.transforms.polygon_to_line + mapshader.transforms.raster_to_categorical_points + mapshader.transforms.get_transform_by_name \ No newline at end of file diff --git a/docs/source/releases.json b/docs/source/releases.json new file mode 100644 index 0000000..48a1989 --- /dev/null +++ b/docs/source/releases.json @@ -0,0 +1,4 @@ +{ + "latest": "https://mapshader.org/index.html", + "0.1.0": "https://mapshader.org/v0.1.0/index.html" +} \ No newline at end of file diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt new file mode 100644 index 0000000..7f220cc --- /dev/null +++ b/docs/source/requirements.txt @@ -0,0 +1,3 @@ +pydata_sphinx_theme +sphinx +sphinx-multiversion \ No newline at end of file