From ef5894b407f93809e878f133b203f0fb7ef81df1 Mon Sep 17 00:00:00 2001 From: Thor77 Date: Tue, 18 Apr 2017 23:24:30 +0200 Subject: [PATCH] Refactor documentation * move documentation-source from /docs/source to /docs/ and build in /docs/_build instead of /docs/build * convert README to rst and remove information also present in documentation and refer to it * regenerate conf.py/Makefile with most recent Sphinx-version * add development.rst with information for contributors --- .gitignore | 2 + README.md | 82 -------------- README.rst | 50 +++++++++ docs/Makefile | 194 ++------------------------------- docs/{source => }/api.rst | 14 +-- docs/cli.rst | 30 +++++ docs/{source => }/conf.py | 94 ++++++++++++---- docs/config.rst | 40 +++++++ docs/development.rst | 35 ++++++ docs/{source => }/identmap.rst | 3 +- docs/index.rst | 13 +++ docs/source/cli.rst | 2 - docs/source/config.rst | 68 ------------ docs/source/index.rst | 16 --- docs/source/quickstart.rst | 37 ------- 15 files changed, 261 insertions(+), 419 deletions(-) delete mode 100644 README.md create mode 100644 README.rst rename docs/{source => }/api.rst (92%) create mode 100644 docs/cli.rst rename docs/{source => }/conf.py (59%) create mode 100644 docs/config.rst create mode 100644 docs/development.rst rename docs/{source => }/identmap.rst (99%) create mode 100644 docs/index.rst delete mode 100644 docs/source/cli.rst delete mode 100644 docs/source/config.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/quickstart.rst diff --git a/.gitignore b/.gitignore index 24d7545..3560abf 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ build/ dist/ *.egg-info/ *.egg + +docs/_build diff --git a/README.md b/README.md deleted file mode 100644 index 9c94818..0000000 --- a/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# TeamspeakStats [![Build Status](https://travis-ci.org/Thor77/TeamspeakStats.svg?branch=master)](https://travis-ci.org/Thor77/TeamspeakStats) [![Build status](https://ci.appveyor.com/api/projects/status/u9cx7krwmmevbvl2?svg=true)](https://ci.appveyor.com/project/Thor77/teamspeakstats) [![Coverage Status](https://coveralls.io/repos/Thor77/TeamspeakStats/badge.svg?branch=master&service=github)](https://coveralls.io/github/Thor77/TeamspeakStats?branch=master) [![Code Health](https://landscape.io/github/Thor77/TeamspeakStats/master/landscape.svg?style=flat)](https://landscape.io/github/Thor77/TeamspeakStats/master) [![PyPI](https://img.shields.io/pypi/v/tsstats.svg)](https://pypi.python.org/pypi/tsstats) [![Documentation Status](https://readthedocs.org/projects/teamspeakstats/badge/?version=latest)](http://teamspeakstats.readthedocs.io/en/latest/?badge=latest) -A simple Teamspeak stat-generator - based solely on server-logs - -![screenshot](screenshot.png) - -# Installation -- Install the package via PyPi `pip install tsstats` -- Clone this repo `git clone https://github.com/Thor77/TeamspeakStats` and install with `python setup.py install` -- Just use the package as is via `python -m tsstats [-h]` - -# Usage -- Run the script `tsstats [-h]` -- Optionally create a config-file (see [Configuration](https://github.com/Thor77/TeamspeakStats#configuration)) -- The package works entirely off your Teamspeak server's logs, so that no ServerQuery account is necessary - -# Example -``` -tsstats -l /var/log/teamspeak3-server/ts3server*.log -o /var/www/tsstats.html -``` - -Parse logs matching `ts3server*.log` in `/var/log/teamspeak3-server` and write output to `/var/www/tsstats.html`. - -# CLI-Usage -``` -usage: tsstats [-h] [-c CONFIG] [--idmap IDMAP] [-l LOG] [-o OUTPUT] [-d] - [-ds] [-nod] [-t TEMPLATE] [-dtf DATETIMEFORMAT] - [-otth ONLINETIMETHRESHOLD] - -A simple Teamspeak stats-generator, based solely on server-logs - -optional arguments: - -h, --help show this help message and exit - -c CONFIG, --config CONFIG - path to config - --idmap IDMAP path to id_map - -l LOG, --log LOG path to your logfile(s) - -o OUTPUT, --output OUTPUT - path to the output-file - -d, --debug debug mode - -ds, --debugstdout write debug output to stdout - -nod, --noonlinedc don't add connect until now to onlinetime - -t TEMPLATE, --template TEMPLATE - path to custom template - -dtf DATETIMEFORMAT, --datetimeformat DATETIMEFORMAT - format of date/time-values (datetime.strftime) - -otth ONLINETIMETHRESHOLD, --onlinetimethreshold ONLINETIMETHRESHOLD - threshold for displaying onlinetime (in seconds) -``` - -# Configuration - -#### [General] -| Key | Description | -|-----|-------------| -| log | Path to TS3Server-logfile(s) (supports [globbing](https://docs.python.org/3/library/glob.html)) | -| output | Path to the location, where the generator will put the generated `.html`-file | -| idmap | Path to [IdentMap](http://teamspeakstats.readthedocs.io/en/latest/identmap.html) | -| debug | debug mode | -| debugstdout | write debug output (only) to stdout | -| onlinedc | Add timedelta from last-connect until now to onlinetime for connected clients | -| template | Path to a custom template file (relative from `tsstats/` or absolute) | -| datetimeformat | Format of date/time-values used for render-timestamp and last online (using [datetime.strftime](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)) | -| onlinetimethreshold | Clients with an onlinetime below that threshold (in seconds) are hidden in the onlinetime-section | - - -## Example -``` -[General] -log = /usr/local/bin/teamspeak-server/logs/ts3server*_1.log -output = /var/www/html/stats.html -``` - -# Contributing -Please make sure tests are succeeding and your code follows [flake8](https://flake8.readthedocs.io)-guidelines. - -## Run tests -- Install testing-requirements `pip install -r testing_requirements.txt` -- Run `py.test tsstats/` - -## Supported Python-versions -* Python 2 (2.7) -* Python 3 (3.5, 3.6) diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..ab476a9 --- /dev/null +++ b/README.rst @@ -0,0 +1,50 @@ +TeamspeakStats |Build Status| |Build status| |Coverage Status| |Code Health| |PyPI| |Documentation Status| +========================================================================================================== + +A simple Teamspeak stat-generator - based solely on server-logs + +|screenshot| + +Installation +============ + +- Install the package via PyPi ``pip install tsstats`` +- Clone this repo + ``git clone https://github.com/Thor77/TeamspeakStats`` and install + with ``python setup.py install`` +- Just use the package as is via ``python -m tsstats [-h]`` + +Usage +===== + +- Run the script ``tsstats [-h]`` +- Optionally create a config-file (see + `Configuration `__) +- The package works entirely off your Teamspeak server's logs, so that + no ServerQuery account is necessary + +Example +======= + +:: + + tsstats -l /var/log/teamspeak3-server/ts3server*.log -o /var/www/tsstats.html + +Parse logs matching ``ts3server*.log`` in ``/var/log/teamspeak3-server`` +and write output to ``/var/www/tsstats.html``. + +For more details checkout the `documentation `__! + +.. |screenshot| image:: https://raw.githubusercontent.com/Thor77/TeamspeakStats/master/screenshot.png +.. |Build Status| image:: https://travis-ci.org/Thor77/TeamspeakStats.svg?branch=master + :target: https://travis-ci.org/Thor77/TeamspeakStats +.. |Build status| image:: https://ci.appveyor.com/api/projects/status/u9cx7krwmmevbvl2?svg=true + :target: https://ci.appveyor.com/project/Thor77/teamspeakstats +.. |Coverage Status| image:: https://coveralls.io/repos/Thor77/TeamspeakStats/badge.svg?branch=master&service=github + :target: https://coveralls.io/github/Thor77/TeamspeakStats?branch=master +.. |Code Health| image:: https://landscape.io/github/Thor77/TeamspeakStats/master/landscape.svg?style=flat + :target: https://landscape.io/github/Thor77/TeamspeakStats/master +.. |PyPI| image:: https://img.shields.io/pypi/v/tsstats.svg + :target: https://pypi.python.org/pypi/tsstats +.. |Documentation Status| image:: https://readthedocs.org/projects/teamspeakstats/badge/?version=latest + :target: http://teamspeakstats.readthedocs.io/en/latest/?badge=latest diff --git a/docs/Makefile b/docs/Makefile index 991e2ec..3a4146c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,192 +1,20 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext +SPHINXPROJ = TeamspeakStats +SOURCEDIR = . +BUILDDIR = _build +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -clean: - rm -rf $(BUILDDIR)/* +.PHONY: help Makefile -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/TeamspeakStats.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/TeamspeakStats.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/TeamspeakStats" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TeamspeakStats" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +# 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) \ No newline at end of file diff --git a/docs/source/api.rst b/docs/api.rst similarity index 92% rename from docs/source/api.rst rename to docs/api.rst index 2b0bdf6..d6f8d46 100644 --- a/docs/source/api.rst +++ b/docs/api.rst @@ -1,14 +1,14 @@ API -*** +=== Log -=== +--- .. automodule:: tsstats.log :members: Client -====== +------ .. autoclass:: tsstats.client.Client :members: @@ -21,24 +21,24 @@ Client .. automethod:: tsstats.client.Clients.__iter__ Template -======== +-------- .. automodule:: tsstats.template :members: Config -====== +------ .. automodule:: tsstats.config :members: Exceptions -========== +---------- .. automodule:: tsstats.exceptions :members: Utils -===== +----- .. automodule:: tsstats.utils :members: diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 0000000..53fb80b --- /dev/null +++ b/docs/cli.rst @@ -0,0 +1,30 @@ +Command Line Interface +====================== + +.. code-block:: console + + $ tsstats --help + usage: tsstats [-h] [-c CONFIG] [--idmap IDMAP] [-l LOG] [-o OUTPUT] [-d] + [-ds] [-nod] [-t TEMPLATE] [-dtf DATETIMEFORMAT] + [-otth ONLINETIMETHRESHOLD] + + A simple Teamspeak stats-generator, based solely on server-logs + + optional arguments: + -h, --help show this help message and exit + -c CONFIG, --config CONFIG + path to config + --idmap IDMAP path to id_map + -l LOG, --log LOG path to your logfile(s). pass a directory to use all + logfiles inside it + -o OUTPUT, --output OUTPUT + path to the output-file + -d, --debug debug mode + -ds, --debugstdout write debug output to stdout + -nod, --noonlinedc don't add connect until now to onlinetime + -t TEMPLATE, --template TEMPLATE + path to custom template + -dtf DATETIMEFORMAT, --datetimeformat DATETIMEFORMAT + format of date/time-values (datetime.strftime) + -otth ONLINETIMETHRESHOLD, --onlinetimethreshold ONLINETIMETHRESHOLD + threshold for displaying onlinetime (in seconds) diff --git a/docs/source/conf.py b/docs/conf.py similarity index 59% rename from docs/source/conf.py rename to docs/conf.py index 272597d..923c476 100644 --- a/docs/source/conf.py +++ b/docs/conf.py @@ -1,8 +1,7 @@ -#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # TeamspeakStats documentation build configuration file, created by -# sphinx-quickstart on Thu May 12 21:42:11 2016. +# sphinx-quickstart on Tue Apr 18 22:51:54 2017. # # This file is execfile()d with the current directory set to its # containing dir. @@ -13,50 +12,60 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys -import os - # 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. -sys.path.insert(0, os.path.abspath('../..')) +# +import os +import sys + +sys.path.insert(0, os.path.abspath('..')) + # -- General configuration ------------------------------------------------ autodoc_member_order = 'bysource' +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + # 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.viewcode', + 'sphinx.ext.viewcode' ] +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: +# # source_suffix = ['.rst', '.md'] source_suffix = '.rst' -# The encoding of source files. -source_encoding = 'utf-8-sig' - # The master toctree document. master_doc = 'index' # General information about the project. -project = 'TeamspeakStats' -copyright = '2016, Thor77' -author = 'Thor77' +project = u'TeamspeakStats' +copyright = u'2017, Thor77' +author = u'Thor77' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.8' +version = u'1.4' # The full version, including alpha/beta/rc tags. -release = '0.8.0' +release = u'1.4.1' + +# suppres warning about nonlocal images +suppress_warnings = ['image.nonlocal_uri'] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -67,7 +76,8 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -80,19 +90,57 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +# +if os.environ.get('READTHEDOCS') != 'True': + # we're not built by rtd => add rtd-theme + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# 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 = {} + +# 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. htmlhelp_basename = 'TeamspeakStatsdoc' + # -- Options for LaTeX output --------------------------------------------- +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'TeamspeakStats.tex', 'TeamspeakStats Documentation', - 'Thor77', 'manual'), + (master_doc, 'TeamspeakStats.tex', u'TeamspeakStats Documentation', + u'Thor77', 'manual'), ] @@ -101,7 +149,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'teamspeakstats', 'TeamspeakStats Documentation', + (master_doc, 'teamspeakstats', u'TeamspeakStats Documentation', [author], 1) ] @@ -112,7 +160,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'TeamspeakStats', 'TeamspeakStats Documentation', - author, 'TeamspeakStats', 'One line description of project.', - 'Miscellaneous'), + (master_doc, 'TeamspeakStats', u'TeamspeakStats Documentation', + author, 'TeamspeakStats', 'One line description of project.', + 'Miscellaneous'), ] diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 0000000..9d5935e --- /dev/null +++ b/docs/config.rst @@ -0,0 +1,40 @@ +Config +====== + +The configfile is using the .ini-format. +Currently all settings are read from the ``[General]``-section. + ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Key | Description | ++=====================+=================================================================================================================================================================================+ +| log | Path to TS3Server-logfile(s) (supports `globbing `__) | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| output | Path to the location, where the generator will put the generated .html-file | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| idmap | Path to `IdentMap `__ | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| debug | debug mode | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| onlinedc | Add timedelta from last-connect until now to onlinetime for connected clients | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| template | Path to a custom template file (relative from ``tsstats/`` or absolute) | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| datetimeformat | Format of date/time-values used for render-timestamp and last online (using `datetime.strftime `__) | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| onlinetimethreshold | Clients with an onlinetime below that threshold (in seconds) are hidden in the onlinetime-section | ++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Example +------- + +``config.ini`` + +.. code-block:: ini + + [General] + log = /usr/local/bin/teamspeak-server/logs/ts3server*_1.log + output = /var/www/html/stats.html + +.. code-block:: console + + $ tsstats -c config.ini diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..904e3f0 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,35 @@ +Development +=========== + +Contributing +------------ +Contributions are very welcome! + +Before developing a new (possibly breaking) feature, please open an Issue about it first +so we can discuss your idea and possible implementations. + +Please read this document carefully before submitting your Pull Request to avoid failing CI tests. + +Style +----- +Your contribution should pass `flake8 `__ +as well as `isort `__. + +Testing +------- +There are unit tests for all parts of the project built with `py.test `__. +Besides ``py.test`` tests require ``BeautifulSoup`` for template-testing. +Those requirements are listed in ``testing_requirements.txt``:: + + $ pip install -r testing_requirement.txt + $ py.test tsstats/tests/ + +Versioning +---------- +TeamspeakStats uses `Semantic Versioning `__. +Please don't bump versions in your Pull Requests, though, we will do that after merging. + +Python Versions +--------------- +To keep the tool accessible and maintainable at the same time at least ``Python 2.7`` is required, +so keep this in mind when using fancy new features from a recent Python version. diff --git a/docs/source/identmap.rst b/docs/identmap.rst similarity index 99% rename from docs/source/identmap.rst rename to docs/identmap.rst index f10cb32..2c7ce7a 100644 --- a/docs/source/identmap.rst +++ b/docs/identmap.rst @@ -1,5 +1,6 @@ IdentMap -******** +======== + An IdentMap is used to map multiple (U)ID's of one client to one client. This can be useful, if a user creates multiple identities and you want to summarize all actions from all identities. To pass an IdentMap to TeamspeakStats, create your IdentMap as shown above and pass it to the cli:: diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..26c8eab --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,13 @@ +TeamspeakStats Documentation +============================ + +.. toctree:: + :maxdepth: 2 + + cli + config + identmap + api + development + +.. include:: ../README.rst diff --git a/docs/source/cli.rst b/docs/source/cli.rst deleted file mode 100644 index 23ca889..0000000 --- a/docs/source/cli.rst +++ /dev/null @@ -1,2 +0,0 @@ -Command-Line-Interface -********************** diff --git a/docs/source/config.rst b/docs/source/config.rst deleted file mode 100644 index 6af9149..0000000 --- a/docs/source/config.rst +++ /dev/null @@ -1,68 +0,0 @@ -Config -****** -The configfile is using the .ini-format. -Currently all settings are read from the ``[General]``-section. - -+--------+----------------+ -| Key | Description | -+========+================+ -| log | Path to | -| | TS3Server-logf | -| | ile(s) | -| | (supports | -| | `globbing ` | -| | __) | -+--------+----------------+ -| output | Path to the | -| | location, | -| | where the | -| | generator will | -| | put the | -| | generated | -| | ``.html``-file | -+--------+----------------+ -| idmap | Path to | -| | `IdentMap `__ | -+--------+----------------+ -| debug | debug mode | -+--------+----------------+ -| online | Add timedelta | -| dc | from | -| | last-connect | -| | until now to | -| | onlinetime for | -| | connected | -| | clients | -+--------+----------------+ -| templa | Path to a | -| te | custom | -| | template file | -| | (relative from | -| | ``tsstats/`` | -| | or absolute) | -+--------+----------------+ -| dateti | Format of | -| meform | date/time-valu | -| at | es | -| | used for | -| | render-timesta | -| | mp | -| | and last | -| | online (using | -| | `datetime.strf | -| | time `__ | -| | ) | -+--------+----------------+ diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index a02465b..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Welcome to TeamspeakStats's documentation! -========================================== - -This document contains a more in-depth and technical documentation (in contrast to the `README `_) -for TeamspeakStats. - -Contents: - -.. toctree:: - :maxdepth: 2 - - quickstart - cli - config - identmap - api diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst deleted file mode 100644 index 13873a9..0000000 --- a/docs/source/quickstart.rst +++ /dev/null @@ -1,37 +0,0 @@ -Quickstart -********** -First, you have to get and install a decent version of `Python `_ (at least 2.7). -Now you have various options to use TeamspeakStats, going from easy to hard: - -1. Install the tool via pip ``pip install tsstats`` -2. Clone the sourcecode ``git clone https://github.com/Thor77/TeamspeakStats`` - - * **A** Just run the script from your local copy ``python -m tsstats`` - * **B** Install the script with the included *setup.py* ``python setup.py install`` - -To start, you can just use cli-arguments to control the behaviour of TeamspeakStats:: - - usage: tsstats [-h] [-c CONFIG] [--idmap IDMAP] [-l LOG] [-o OUTPUT] [-d] - [-nod] - - A simple Teamspeak stats-generator - based on server-logs - - optional arguments: - -h, --help show this help message and exit - -c CONFIG, --config CONFIG - path to config - --idmap IDMAP path to id_map - -l LOG, --log LOG path to your logfile(s). pass a directory to use all - logfiles inside it - -o OUTPUT, --output OUTPUT - path to the output-file - -d, --debug debug mode - -nod, --noonlinedc don't add connect until now to onlinetime - -t TEMPLATE, --template TEMPLATE - path to custom template - -dtf DATETIMEFORMAT, --datetimeformat DATETIMEFORMAT - format of date/time-values (datetime.strftime) - -Take a look at :doc:`cli` to get a more in-depth explanation of the available flags. -If you want to use TeamspeakStats in a script (or cron) you should consider creating -a :doc:`config`.