From 1b444076c6bac3867b44de857a53aa2a3acc9148 Mon Sep 17 00:00:00 2001 From: Joost Cassee Date: Sun, 30 Jan 2011 16:19:58 +0100 Subject: [PATCH] Improve documentation layout Move author information to AUTHORS.rst. Move changelog to CHANGELOG.rst. Add license to documentation. Fix README.rst. Add documentation source files to revision control. --- AUTHORS.rst | 12 ++++++++++++ CHANGELOG.rst | 12 ++++++++++++ LICENSE.txt | 2 +- README.rst | 37 ++++++++++++++++++++++++------------ docs/conf.py | 6 +++--- docs/{.ext => ext}/local.py | 0 docs/history.rst | 38 +++++++++++++++++++++---------------- docs/index.rst | 24 ++--------------------- docs/license.rst | 16 ++++++++++++++++ setup.py | 2 +- 10 files changed, 94 insertions(+), 55 deletions(-) create mode 100644 AUTHORS.rst create mode 100644 CHANGELOG.rst rename docs/{.ext => ext}/local.py (100%) create mode 100644 docs/license.rst diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 0000000..aa2b47c --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,12 @@ +The django-analytical package is was written by `Joost Cassee`_. +Included Javascript code snippets for integration of the analytics +services was written by the respective service providers. + +The application was inspired by and uses ideas from Analytical_, Joshua +Krall's all-purpose analytics front-end for Rails. + +The work on Crazy Egg was made possible by `Bateau Knowledge`_. + +.. _`Joost Cassee`: mailto:joost@cassee.net +.. _Analytical: https://github.com/jkrall/analytical +.. _`Bateau Knowledge`: http://www.bateauknowledge.nl/ diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..fda6a69 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,12 @@ +Development +----------- +* Added support for the Performable service. + +Version 0.2.0 +------------- +* Added support for the HubSpot service. +* Added template tags for individual services. + +Version 0.1.0 +------------- +* First project release. diff --git a/LICENSE.txt b/LICENSE.txt index c223404..76bd648 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (C) 2011 Joost Cassee +Copyright (C) 2011 Joost Cassee and others Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.rst b/README.rst index c32e25f..1e01807 100644 --- a/README.rst +++ b/README.rst @@ -1,8 +1,21 @@ django-analytical ----------------- -The django-analytical application integrates various analytics services -into a Django_ project. Currently supported services: +The django-analytical application integrates analytics services into a +Django_ project. + +Using an analytics service with a Django project means adding Javascript +tracking code to the project templates. Of course, every service has +its own specific installation instructions. Furthermore, you need to +include your unique identifiers, which then end up in the templates. +This application hides the details of the different analytics services +behind a generic interface, and keeps personal information and +configuration out of the templates. Its goal is to make the basic +set-up very simple, while allowing advanced users to customize tracking. +Each service is set up as recommended by the services themselves, using +an asynchronous version of the Javascript code if possible. + +Currently supported services: * `Chartbeat`_ traffic analysis * `Clicky`_ traffic analysis @@ -15,25 +28,25 @@ into a Django_ project. Currently supported services: * `Optimizely`_ A/B testing The documentation can be found in the ``docs`` directory or `read -online`_. The source code and issue tracker are `hosted on GitHub`_. +online`_. The project source is `hosted by GitHub`_. -Copyright (C) 2011 Joost Cassee . This software is -licensed under the MIT License (see LICENSE.txt). - -This application was inspired by and uses ideas from Analytical_, -Joshua Krall's all-purpose analytics front-end for Rails. The work on -Crazy Egg was made possible by `Bateau Knowledge`_. +If you want to help out with development of django-analytical, by +posting detailed bug reports, suggesting new features or other analytics +services to support, or doing some development work yourself, please use +the `issue tracker`_. If you want to get your hands dirty yourself, +great! Clone the repository, make changes and send a pull request. +Please do create an issue to discuss your plans. .. _Django: http://www.djangoproject.com/ .. _Chartbeat: http://www.chartbeat.com/ .. _Clicky: http://getclicky.com/ .. _`Crazy Egg`: http://www.crazyegg.com/ .. _`Google Analytics`: http://www.google.com/analytics/ +.. _HubSpot: http://www.hubspot.com/ .. _KISSinsights: http://www.kissinsights.com/ .. _KISSmetrics: http://www.kissmetrics.com/ .. _Mixpanel: http://www.mixpanel.com/ .. _Optimizely: http://www.optimizely.com/ .. _`read online`: http://packages.python.org/django-analytical/ -.. _`hosted on GitHub`: http://www.github.com/jcassee/django-analytical -.. _Analytical: https://github.com/jkrall/analytical -.. _`Bateau Knowledge`: http://www.bateauknowledge.nl/ +.. _`hosted by GitHub`: http://github.com/jcassee/django-analytical +.. _`issue tracker`: http://github.com/jcassee/django-analytical/issues diff --git a/docs/conf.py b/docs/conf.py index cecbcd0..646568c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,7 +4,7 @@ # directory. import sys, os -sys.path.append(os.path.join(os.path.abspath('.'), '.ext')) +sys.path.append(os.path.join(os.path.abspath('.'), 'ext')) sys.path.append(os.path.dirname(os.path.abspath('.'))) import analytical @@ -20,7 +20,7 @@ release = analytical.__version__ version = release.rsplit('.', 1)[0] extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'local'] -templates_path = ['.templates'] +templates_path = ['templates'] source_suffix = '.rst' master_doc = 'index' @@ -36,7 +36,7 @@ intersphinx_mapping = { # -- Options for HTML output --------------------------------------------------- html_theme = 'default' -html_static_path = ['.static'] +html_static_path = ['static'] htmlhelp_basename = 'analyticaldoc' diff --git a/docs/.ext/local.py b/docs/ext/local.py similarity index 100% rename from docs/.ext/local.py rename to docs/ext/local.py diff --git a/docs/history.rst b/docs/history.rst index 82f444e..950f2c7 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -5,26 +5,32 @@ History and credits Changelog ========= -0.2.0 ------ -* Added support for the HubSpot service. -* Added template tags for individual services. +The project follows the `Semantic Versioning`_ specification for its +version numbers. Patch-level increments indicate bug fixes, minor +version increments indicate new functionality and major version +increments indicate backwards incompatible changes. + +.. _`Semantic Versioning`: http://semver.org/ + +.. include:: ../CHANGELOG.rst -0.1.0 ------ -* First project release. Credits ======= -django-analytical was written by `Joost Cassee`_. The project source -code is generously hosted by GitHub_. +.. include:: ../AUTHORS.rst -This application was inspired by and uses ideas from Analytical_, -Joshua Krall's all-purpose analytics front-end for Rails. The work on -Crazy Egg was made possible by `Bateau Knowledge`_. -.. _`Joost Cassee`: mailto:joost@cassee.net -.. _GitHub: http://github.com/ -.. _Analytical: https://github.com/jkrall/analytical -.. _`Bateau Knowledge`: http://www.bateauknowledge.nl/ +.. _helping-out: + +Helping out +=========== + +If you want to help out with development of django-analytical, by +posting detailed bug reports, suggesting new features or other analytics +services to support, or doing some development work yourself, please use +the `issue tracker`_. If you want to get your hands dirty yourself, +great! Clone the repository, make changes and send a pull request. +Please do create an issue to discuss your plans. + +.. _`issue tracker`: http://github.com/jcassee/django-analytical/issues diff --git a/docs/index.rst b/docs/index.rst index a9a6563..0f3a311 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ up in the templates. This application hides the details of the different analytics services behind a generic interface, and keeps personal information and configuration out of the templates. Its goal is to make basic usage set-up very simple, while allowing advanced users -to customize tracking. Each service is set-up as recommended by the +to customize tracking. Each service is set up as recommended by the services themselves, using an asynchronous version of the Javascript code if possible. @@ -42,24 +42,4 @@ Contents services settings history - - -.. _helping-out: - -Helping out -=========== - -If you want to help out with development of django-analytical, by -posting detailed bug reports, suggesting new features or other analytics -services to support, or doing some development work yourself, please see -use the `GitHub project page`_. Use the `issue tracker`_ to discuss -bugs and features. - -If you want to work on it yourself, great! Clone the repository, make -changes and send a pull request. Please do create a new issue to -discuss your plans. - -Of course, you can always send ideas and patches to joost@cassee.net. - -.. _`GitHub project page`: http://github.com/jcassee/django-analytical -.. _`issue tracker`: http://github.com/jcassee/django-analytical/issues + license diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..a201747 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,16 @@ +======= +License +======= + +The django-analytical package is distributed under the `MIT License`_. +The complete license term are included below. The copyright of the +integration code snippets of individual services rest solely with the +respective service providers. + +.. _`MIT License`: http://en.wikipedia.org/wiki/MIT_License + + +License terms +============= + +.. include:: ../LICENSE.txt diff --git a/setup.py b/setup.py index 6cedbbc..dcf0dfb 100644 --- a/setup.py +++ b/setup.py @@ -65,7 +65,7 @@ setup( 'Topic :: Software Development :: Libraries :: Python Modules', ], platforms = ['any'], - url = 'http://github.com/jcassee/django-analytical', + url = 'http://packages.python.org/django-analytical/', download_url = 'http://github.com/jcassee/django-analytical/archives/master', cmdclass = cmdclass, )