Documentation.

Squashed commit of the following:

commit a20f2ca
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:58:12 2020 +0800

    Add doc link in README.

commit fe89368
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:52:34 2020 +0800

    Fix index doc issue.

commit 04157d2
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:43:42 2020 +0800

    Fix docs requirements.

commit 1fa7fb3
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:32:41 2020 +0800

    Add DOCS_REQUIRES in setup.py.

commit 1074cf3
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:24:11 2020 +0800

    More badges.

commit e57d543
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:08:20 2020 +0800

    Add doc and download badge.

commit 890a708
Author: huxuan <[email protected]>
Date:   Sun Jan 12 21:03:23 2020 +0800

    Docs finally.

commit 87cc413
Author: huxuan <[email protected]>
Date:   Fri Jan 10 15:54:06 2020 +0800

    Better version.

commit 06336cc
Author: huxuan <[email protected]>
Date:   Tue Jan 7 20:57:34 2020 +0800

    Add prerequisites in README.

Makefile

@@ -1,11 +1,11 @@
-.PHONY: clean install dev lint pycodestyle pyflakes pylint dist upload
+.PHONY: clean install dev lint pycodestyle pyflakes pylint dist upload docs
 
 clean:
 	find . -name '*.pyc' -print0 | xargs -0 rm -f
 	find . -name '*.swp' -print0 | xargs -0 rm -f
 	find . -name '.DS_Store' -print0 | xargs -0 rm -rf
 	find . -name '__pycache__' -print0 | xargs -0 rm -rf
-	-rm -rf build dist *.egg-info .eggs *.spec
+	-rm -rf build dist *.egg-info .eggs *.spec docs/_build
 
 install:
 	pip install .
@@ -29,3 +29,9 @@ dist: clean
 
 upload:
 	twine upload dist/*
+
+docs: clean install
+	cd docs && make html
+
+docsdeps:
+	pip install -r docs/requirements.txt

README.md

@@ -1,12 +1,16 @@
-# iptvtools
+# IPTVTools
 
 [![PyPI version](https://badge.fury.io/py/iptvtools.svg)](https://badge.fury.io/py/iptvtools)
+[![Documentation Status](https://readthedocs.org/projects/iptvtools/badge/?version=latest)](https://iptvtools.readthedocs.io/en/latest/?badge=latest)
+[![PyPI license](https://img.shields.io/pypi/l/iptvtools.svg)](https://pypi.python.org/pypi/iptvtools/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/iptvtools.svg)](https://pypi.python.org/pypi/iptvtools/)
+[![Downloads](https://pepy.tech/badge/iptvtools)](https://pepy.tech/project/iptvtools)
 
 Scripts currently provided:
 
 - [iptv-filter](https://github.com/huxuan/iptvtools/wiki/iptv%E2%80%90filter)
   - Merge from different resources.
-  - Check the connectivity.
+  - Check the tcp/udp connectivity.
   - Filter by custom criteria, e.g. resolution.
   - Match with templates and EPG.
   - Format the url with UDPxy if provided.
@@ -21,6 +25,10 @@ Besides, all scripts should be lightweight and able to keep running regularly af
 
 Last but not least, any ideas, comments and suggestions are welcome!
 
+## Prerequisites
+
+To filter by stream information, e.g., resolution/height, [ffmpeg](https://www.ffmpeg.org/) (or [ffprobe](https://www.ffmpeg.org/ffprobe.html) more precisely) is needed, please install according to the [documentation](https://www.ffmpeg.org/download.html).
+
 ## Installation
 
 ```shell
@@ -29,4 +37,4 @@ pip install -U iptvtools
 
 ## Usage
 
-Please refer to the [wiki](https://github.com/huxuan/iptvtools/wiki) page.
+Please refer to the [documentation](https://iptvtools.readthedocs.io/) while some useful information in [wiki](https://github.com/huxuan/iptvtools/wiki).

docs/Makefile

@@ -0,0 +1,20 @@
+# 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)
+
+.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)

docs/conf.py

@@ -0,0 +1,56 @@
+# 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
+sys.path.insert(0, os.path.abspath('..'))
+import iptvtools
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'IPTVTools'
+copyright = '2020, Xuan (Sean) Hu'
+author = 'Xuan (Sean) Hu'
+version = iptvtools.__version__
+release = iptvtools.__version__
+
+# -- 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 = [
+    'sphinxcontrib.programoutput',
+]
+
+# 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']
+
+master_doc = "index"
+
+# -- 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 = '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']

docs/index.rst

@@ -0,0 +1,21 @@
+.. IPTVTools documentation master file, created by
+   sphinx-quickstart on Sat Jan 11 12:07:20 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to IPTVTools's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   scripts
+   parameters
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,12 @@
+Installation
+============
+
+The simplest way to install is downloading from PyPI::
+
+    $ pip install -U iptvtools
+
+If you prefer the latest master branch or want to make some code changes, you can download and install with the following command::
+
+    $ git clone https://github.com/huxuan/iptvtools.git
+    $ cd iptvtools
+    $ pip install .

docs/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

docs/parameters.rst

@@ -0,0 +1,64 @@
+Selected Parameters
+===================
+
+MIN_HEIGHT
+----------
+
+HEIGHT is a dominant factor of stream quality,
+where 1080 in height means 1080p.
+It is necessary to set this filter
+if the stream is supposed to be shown on high resolution screens,
+e.g., a 4K TV.
+
+CONFIG
+------
+
+`CONFIG <https://github.com/huxuan/iptvtools/blob/master/config.json>`_
+is a customized configuration to unify ``title`` and ``id``.
+``title`` is the exact title which will be shown and
+the ``id`` is used for potential match with the template.
+A general idea is to make the ``id`` as simple as possible
+so they will have a high possibility to match,
+though there might be some false positive cases.
+So, ``id_unifiers`` can be treated as
+a further simplification of ``titile_unifier``.
+
+For example, entry ``"-": ""`` will convert ``CCTV-1`` to ``CCTV1``,
+entry ``"＋": "+"`` will convert ``CCTV-5＋`` to ``CCTV-5+``.
+A whole replacement is also possible,
+as ``"BTV冬奥纪实": "北京纪实"`` will
+match the whole of ``BTV冬奥纪实`` and
+replace it with ``北京纪实``.
+
+Please be caution about using too many of them
+since this simplified strategy is just for some basic requirement.
+Some entries may lead to some unexpected changes.
+For example, entry ``"CCTV-1": "中央1套"`` will convert ``CCTV-11`` to ``中央1套1``.
+So, in generally,
+only keep those necessary entries and keep it as simple as possible.
+
+TEMPLATE
+--------
+
+A m3u playlist with well-maintained information to cooperate with EPG.
+Please refer to `Well‐maintained templates & EPGs <https://github.com/huxuan/iptvtools/wiki/Well%E2%80%90maintained-templates-&-EPGs>`_.
+
+BTW, there is also a list `Well‐maintained playlists <https://github.com/huxuan/iptvtools/wiki/Well%E2%80%90maintained-playlists>`_.
+
+TIMEOUT
+-------
+
+TIMEOUT is used to check the connectivity.
+Direct check which only fecth the response header tends to be fast.
+But it usually takes seconds to probe stream information
+depends on your network (bandwidth and latency).
+For me, it is about 3 to 5 seconds.
+
+UDPXY
+-----
+
+If the IPTV streams is forwarded by UPDXY,
+setting it will convert all the urls automatically.
+For examples, with UDPXY ``http://192.168.0.1:8888/``,
+``rtp://123.45.67.89:1234`` will be converted to
+``http://192.168.0.1:8888/rtp/123.45.67.89:1234``.

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinxcontrib-programoutput

docs/scripts.rst

@@ -0,0 +1,7 @@
+Scripts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   scripts/iptv-filter

docs/scripts/iptv-filter.rst

@@ -0,0 +1,27 @@
+:tocdepth: 1
+
+iptv-filter
+===========
+
+Usage
+-----
+
+.. program-output:: iptv-filter -h
+
+Example
+-------
+
+There is a `well-maintained IPTV list <https://gist.github.com/sdhzdmzzl/93cf74947770066743fff7c7f4fc5820>`_ only for Beijing Unicom and a `well-maintained templates & EPG <http://epg.51zmt.top:8000/>`_ mainly for China. So for me::
+
+   $ iptv-filter \
+   -i https://gist.githubusercontent.com/sdhzdmzzl/93cf74947770066743fff7c7f4fc5820/raw/0be4160f4024320f23daad65bce79e606da47995/bj-unicom-iptv.m3u \
+   -t http://epg.51zmt.top:8000/test.m3u
+
+With UDPXY, it becomes::
+
+   $ iptv-filter \
+   -i https://gist.githubusercontent.com/sdhzdmzzl/93cf74947770066743fff7c7f4fc5820/raw/0be4160f4024320f23daad65bce79e606da47995/bj-unicom-iptv.m3u \
+   -t http://epg.51zmt.top:8000/test.m3u \
+   -u http://192.168.0.1:8888
+
+Just replace ``http://192.168.0.1:8888`` with corresponding UDPXY prefix should be OK.

iptvtools/__init__.py

@@ -6,4 +6,4 @@
 Email: i(at)huxuan.org
 Description: iptvtools package.
 """
-__version__ = '0.1.5'
+__version__ = '0.1.6'

setup.py

@@ -9,7 +9,7 @@
 from setuptools import find_packages
 from setuptools import setup
 
-import iptvtools
+from iptvtools import __version__
 
 DESCRIPTION = (
     'A set of scripts that help to better IPTV experience.'
@@ -46,7 +46,7 @@ def readme():
 
 
 setup(name='iptvtools',
-      version=iptvtools.__version__,
+      version=__version__,
       description=DESCRIPTION,
       long_description=readme(),
       long_description_content_type='text/markdown',