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
This commit is contained in:
Thor77
parent
97d58254b3
commit
ef5894b407
|
|
@ -6,3 +6,5 @@ build/
|
|||
dist/
|
||||
*.egg-info/
|
||||
*.egg
|
||||
|
||||
docs/_build
|
||||
|
|
|
|||
82
README.md
82
README.md
|
|
@ -1,82 +0,0 @@
|
|||
# TeamspeakStats [](https://travis-ci.org/Thor77/TeamspeakStats) [](https://ci.appveyor.com/project/Thor77/teamspeakstats) [](https://coveralls.io/github/Thor77/TeamspeakStats?branch=master) [](https://landscape.io/github/Thor77/TeamspeakStats/master) [](https://pypi.python.org/pypi/tsstats) [](http://teamspeakstats.readthedocs.io/en/latest/?badge=latest)
|
||||
A simple Teamspeak stat-generator - based solely on server-logs
|
||||
|
||||
|
||||
|
||||
# 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)
|
||||
|
|
@ -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 <https://teamspeakstats.readthedocs.io/en/latest/config.html>`__)
|
||||
- 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 <http://teamspeakstats.readthedocs.io/en/latest/>`__!
|
||||
|
||||
.. |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
|
||||
194
docs/Makefile
194
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 <target>' where <target> 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)
|
||||
|
|
@ -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:
|
||||
|
|
@ -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)
|
||||
|
|
@ -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',
|
||||
(master_doc, 'TeamspeakStats', u'TeamspeakStats Documentation',
|
||||
author, 'TeamspeakStats', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
|
@ -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 <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 <https://teamspeakstats.readthedocs.io/en/latest/identmap.html>`__ |
|
||||
+---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 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 <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
|
||||
-------
|
||||
|
||||
``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
|
||||
|
|
@ -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 <https://flake8.readthedocs.io>`__
|
||||
as well as `isort <https://github.com/timothycrosley/isort>`__.
|
||||
|
||||
Testing
|
||||
-------
|
||||
There are unit tests for all parts of the project built with `py.test <https://docs.pytest.org>`__.
|
||||
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 <http://semver.org/>`__.
|
||||
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.
|
||||
|
|
@ -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::
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
TeamspeakStats Documentation
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
cli
|
||||
config
|
||||
identmap
|
||||
api
|
||||
development
|
||||
|
||||
.. include:: ../README.rst
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Command-Line-Interface
|
||||
**********************
|
||||
|
|
@ -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 <htt |
|
||||
| | ps://docs.pyth |
|
||||
| | on.org/3/libra |
|
||||
| | ry/glob.html>` |
|
||||
| | __) |
|
||||
+--------+----------------+
|
||||
| output | Path to the |
|
||||
| | location, |
|
||||
| | where the |
|
||||
| | generator will |
|
||||
| | put the |
|
||||
| | generated |
|
||||
| | ``.html``-file |
|
||||
+--------+----------------+
|
||||
| idmap | Path to |
|
||||
| | `IdentMap <htt |
|
||||
| | p://teamspeaks |
|
||||
| | tats.readthedo |
|
||||
| | cs.io/en/lates |
|
||||
| | t/identmap.htm |
|
||||
| | l>`__ |
|
||||
+--------+----------------+
|
||||
| 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 <https:// |
|
||||
| | docs.python.or |
|
||||
| | g/3/library/da |
|
||||
| | tetime.html#st |
|
||||
| | rftime-strptim |
|
||||
| | e-behavior>`__ |
|
||||
| | ) |
|
||||
+--------+----------------+
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
Welcome to TeamspeakStats's documentation!
|
||||
==========================================
|
||||
|
||||
This document contains a more in-depth and technical documentation (in contrast to the `README <https://github.com/Thor77/TeamspeakStats/blob/master/README.md>`_)
|
||||
for TeamspeakStats.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
cli
|
||||
config
|
||||
identmap
|
||||
api
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
Quickstart
|
||||
**********
|
||||
First, you have to get and install a decent version of `Python <https://python.org/>`_ (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`.
|
||||
Loading…
Reference in New Issue