diff --git a/Makefile b/Makefile index 4601c1a..f7a5697 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 42e2c14..cc5bdaf 100644 --- a/README.md +++ b/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). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..bfce1cf --- /dev/null +++ b/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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7376abe --- /dev/null +++ b/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` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..f45fa98 --- /dev/null +++ b/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 . diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/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 diff --git a/docs/parameters.rst b/docs/parameters.rst new file mode 100644 index 0000000..7b3238a --- /dev/null +++ b/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 `_ +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 `_. + +BTW, there is also a list `Well‐maintained 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``. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..fb5bf2d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx +sphinxcontrib-programoutput diff --git a/docs/scripts.rst b/docs/scripts.rst new file mode 100644 index 0000000..a1ed370 --- /dev/null +++ b/docs/scripts.rst @@ -0,0 +1,7 @@ +Scripts +============ + +.. toctree:: + :maxdepth: 1 + + scripts/iptv-filter diff --git a/docs/scripts/iptv-filter.rst b/docs/scripts/iptv-filter.rst new file mode 100644 index 0000000..269b498 --- /dev/null +++ b/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 `_ only for Beijing Unicom and a `well-maintained templates & EPG `_ 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. diff --git a/iptvtools/__init__.py b/iptvtools/__init__.py index b82f63b..379293d 100644 --- a/iptvtools/__init__.py +++ b/iptvtools/__init__.py @@ -6,4 +6,4 @@ Email: i(at)huxuan.org Description: iptvtools package. """ -__version__ = '0.1.5' +__version__ = '0.1.6' diff --git a/setup.py b/setup.py index f48cdea..7d9d845 100644 --- a/setup.py +++ b/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',