documentation started

docsrc/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+#
+github:
+	@make html
+	@cp -a _build/html/. ../docs
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

docsrc/conf.py

@@ -0,0 +1,57 @@
+# 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 sys
+import sphinx_rtd_theme
+sys.path.insert(0, os.path.abspath('../pyimgbatch/'))
+print(os.path.abspath('../pyimgbatch/'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'PyImgBatch'
+copyright = '2019, Sören Kirchner'
+author = 'Sören Kirchner'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1'
+
+
+# -- 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.coverage', 'sphinx.ext.napoleon', "sphinx_rtd_theme"]
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- 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 = 'alabaster'
+# import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+
+# 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']

docsrc/index.rst

@@ -0,0 +1,25 @@
+.. PyImgBatch documentation master file, created by
+   sphinx-quickstart on Sun Oct 13 20:20:09 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to PyImgBatch's documentation!
+======================================
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickstart
+   tutorials
+   parameters
+   pyimgbatch
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docsrc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docsrc/parameters.rst

@@ -0,0 +1,14 @@
+Parameters
+==========
+
+List of **pyimgbatch** project file parameters. The content of the square brackets shows the command line equivalent. 
+
+:width [-\\-width]: **Width** of the destination image. If the **width** is not given, it calculateted on the height. 
+    If neither the width nor the height are given, the width and the height of the source image will be used. 
+
+:height [-\\-height]: **Height** of the destination image. If the **height** is not given, it calculateted on the height.
+    If neither the width nor the height are given, the width and the height of the source image will be used.
+
+:resample [-\\-resample]: defines the resample mode on resizing the image. Possible values are 
+    "none", "bilinear", "bicubic", "hamming", "box" or "antialias". 
+    If there is no resample mode is given or the given resample mode is unknown, it defaults to "antialias"

docsrc/pyimgbatch.rst

@@ -0,0 +1,5 @@
+PyImgBatch
+==========
+
+.. automodule:: pyimgbatch
+    :members:

docsrc/quickstart.rst

@@ -0,0 +1,196 @@
+Quickstart
+==========
+
+PyImgBatch is a batch image processor for python including a command
+line interface.
+
+Installation
+------------
+
+For installation open a terminal and type the following line into the
+command line.
+
+::
+
+    pip install pyimgbatch
+
+Usage on command line
+---------------------
+
+The simplest usage is to change to the folder containing the images with
+
+::
+
+    cd /folder/wit/images
+
+and type
+
+::
+
+    pyimgbatch --width 300
+
+This will resize all supported image files in the current folder to a
+width of 300 pixels respecting the aspect ratio of the source file. The
+results will be written to a "dest" subfolder.
+
+Alternatively, you can set a source folder with the images to be
+converted and/or a destination folder for the results as follow.
+
+::
+
+    pyimgbatch --source source_folder --dest destination_folder --height 400
+
+or shorter
+
+::
+
+    pyimgbatch -s source_folder -d destination_folder --height 400
+
+This will convert the images from the *source\_folder* to a height of
+400px and stores the results in the destination folder.
+
+*Note: For every source image a subfolder will be created inside the
+destination\_folder. To avoid this behavior use the --nosubfolder
+argument.*
+
+Project Files
+-------------
+
+One of PyImgBatch features is to create multiple different versions from
+given image files.
+
+For this, you can use project files. Project files are JSON files
+containing the specifications for the image processing.
+
+The very short one
+~~~~~~~~~~~~~~~~~~
+
+Here an example of a very short one.
+
+.. code:: json
+
+    [
+        { "width": 1000, "suffix": ".w1000" },
+        { "height": 1200, "suffix": ".h1200" }
+    ]
+
+For example (may the project named "myprj.json"):
+
+::
+
+    pyimgbatch -c myprj.json
+
+produces the following output:
+
+::
+
+    creating: french-bulldog-4530685.w1000.jpg
+    creating: french-bulldog-4530685.h1200.jpg
+    creating: coast-4478424.w1000.jpg
+    creating: coast-4478424.h1200.jpg
+    ...
+    creating: beaded-2137080_1920-cmyk-iso-eci.w1000.jpg
+    creating: beaded-2137080_1920-cmyk-iso-eci.h1200.jpg
+    ...
+
+and creates two images per source images, resized to the specified width
+or height with suffix added to the original name.
+
+The short one
+~~~~~~~~~~~~~
+
+Imagine, you need to create different sizes for all your images for
+your web project. For instance, you need the images in widths 180px,
+300px, 400px and one in a height of 800 and each 2x and 3x the size for
+higher pixel density display like in smartphones.
+
+An example could look as follow.
+
+.. code:: JSON
+
+    {
+        "name": "web set",
+        "comment": "some sample pictures",
+        "source": "webset/source",
+        "dest": "webset/dest",
+        "prefix": "web.",
+        "configs": [
+            { "width": 180, "suffix": ".w180", "webset": "@3x" },
+            { "width": 300, "suffix": ".w300", "webset": "@3x" },
+            { "width": 400, "suffix": ".w400", "webset": "@3x" },
+            { "height": 800, "prefix": "preview.", "webset": "@3x" }
+        ]
+    }
+
+This will create 12 destination images for each imput image. For a image
+"lama-4540160.jpg" you get:
+
+::
+
+    ...
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    creating: lama-4540160/[email protected]
+    ...
+
+As you see you can specify defaults, so you don't need to repeat
+yourself.
+
+The more specific option is used instead of the more general one. So
+in this example, all images get the prefix "web." except the last,
+because the more specific prefix is here given as "preview."
+
+*Hint: The file names are a little strange because I've downloaded the
+from the free image stock `pixabay <https://pixabay.com>`__ and I
+haven't changed the Name so you can search for the pics or the
+photographer if you want.*
+
+Full image project file
+~~~~~~~~~~~~~~~~~~~~~~~
+
+looks as follow.
+
+.. code:: JSON
+
+    {
+        "comment": "pyImgBatch demo project",
+        "debug": true,
+        "no-progess": false,
+        "projects": [
+            {
+                "name": "web set",
+                "comment": "some sample pictures",
+                "source": "webset/source",
+                "dest": "webset/dest",
+                "prefix": "web.",
+                "configs": [
+                    { "width": 180, "suffix": ".w180", "webset": "@3x" },
+                    { "width": 300, "suffix": ".w300", "webset": "@3x" },
+                    { "width": 400, "suffix": ".w400", "webset": "@3x" },
+                    { "height": 800, "prefix": "preview.", "webset": "@3x" }
+                ]
+            },
+            {
+                "name": "images to thumbnails",
+                "source": "to-thumbnails/originals",
+                "dest": "to-thumbnails/thumbnails",
+                "subfolder": false,
+                "prefix": "thumb.",
+                "configs": [
+                    {"height": 300}, 
+                    {"prefix": "smallthumb.", "height": 200}
+                ]
+            }
+        ]
+    }
+
+This project contains two projects.

docsrc/tutorials.rst

@@ -0,0 +1,3 @@
+Tutorials
+=========
+