setting up proper documentation; isort & black

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+exclude = .git,__pycache__,docs/_src/conf.py,build,dist
+max-complexity = 10
+max-line-length = 120

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017, Brad Montgomery <[email protected]>
+Copyright (c) 2022, Brad Montgomery <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

docs/_src/configuration.md

@@ -1,3 +1,68 @@
 # Configuration
 
-TBD
+There are two possible settings for this app: The first defines threshold
+values used to color output, while the second allows you customize requests
+that will be ignored by the middleware. The default settings are:
+
+```python
+QUERYCOUNT = {
+    'THRESHOLDS': {
+        'MEDIUM': 50,
+        'HIGH': 200,
+        'MIN_TIME_TO_LOG':0,
+        'MIN_QUERY_COUNT_TO_LOG':0
+    },
+    'IGNORE_REQUEST_PATTERNS': [],
+    'IGNORE_SQL_PATTERNS': [],
+    'DISPLAY_DUPLICATES': None,
+    'RESPONSE_HEADER': 'X-DjangoQueryCount-Count'
+}
+```
+
+The `QUERYCOUNT['THRESHOLDS']` settings will determine how many queries are
+interpreted as high or medium (and the color-coded output). In previous versions
+of this app, this settings was called `QUERYCOUNT_THRESHOLDS` and that setting
+is still supported.
+
+The `QUERYCOUNT['IGNORE_REQUEST_PATTERNS']` setting allows you to define a list of
+regexp patterns that get applied to each request's path. If there is a match,
+the middleware will not be applied to that request. For example, the following
+setting would bypass the querycount middleware for all requests to the admin:
+
+```python
+QUERYCOUNT = {
+    'IGNORE_REQUEST_PATTERNS': [r'^/admin/']
+}
+```
+
+The `QUERYCOUNT['IGNORE_SQL_PATTERNS']` setting allows you to define a list of
+regexp patterns that ignored to statistic sql query count. For example, the following
+setting would bypass the querycount middleware for django-silk sql query:
+
+```python
+QUERYCOUNT = {
+    'IGNORE_SQL_PATTERNS': [r'silk_']
+}
+```
+
+The `QUERYCOUNT['RESPONSE_HEADER']` setting allows you to define a custom response
+header that contains the total number of queries executed. To disable this header,
+the supply `None` as the value:
+
+```python
+QUERYCOUNT = {
+    'RESPONSE_HEADER': None
+}
+```
+
+_New in 0.4.0_. The `QUERYCOUNT['DISPLAY_DUPLICATES']` setting allows you
+to control how the most common duplicate queries are displayed. If the setting
+is `None` (the default), duplicate queries are not displayed. Otherwise, this
+should be an integer. For example, the following setting would always print the
+5 most duplicated queries:
+
+```python
+QUERYCOUNT = {
+    'DISPLAY_DUPLICATES': 5,
+}
+```

docs/_src/contributing.md

@@ -0,0 +1,8 @@
+# Contributing
+
+Bug fixes and new features are welcome!
+
+To contribute, [fork this project](https://github.com/bradmontgomery/django-querycount/),
+and open a Pull Request to have your work included.
+
+Be sure to add yourself to the `AUTHORS.md` file.

docs/_src/index.rst

@@ -1,19 +1,36 @@
 .. django-querycount documentation master file, created by
+   sphinx-quickstart on Tue Dec 13 15:32:52 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
+Welcome to django-querycount's documentation!
+=============================================
 
-Welcome to the django-querycount documentation!
-===============================================
+Inspired by `this post by David Szotten <http://goo.gl/UUKN0r>`_, this project
+gives you a middleware that prints database query counts in Django's runserver
+console output.
+
+|screenshot|
+
+Documentation
+-------------
 
 .. toctree::
-:maxdepth: 2
-:caption: Contents:
+   :maxdepth: 2
+   :caption: Contents:
 
-   Installation <installation.md>
-   Configuration <configuration.md>
+   installation
+   configuration
+   testing
+   contributing
+   license
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`
+
+.. |screenshot| image:: ../screenshot.png
+    :alt: django-querycount in action

docs/_src/installation.md

@@ -1,3 +1,14 @@
 # Installation
 
-TBD
+Install with pip:
+
+```
+pip install django-querycount
+```
+
+Then add `querycount.middleware.QueryCountMiddleware` to your
+`MIDDLEWARE`.
+
+Notice that `django-querycount` only works while your project is in DEBUG mode.
+
+If you must, download a source distribution from [pypi.org/project/django-querycount/](https://pypi.org/project/django-querycount/)

docs/_src/license.md

@@ -0,0 +1,23 @@
+# License
+
+This code is distributed under the terms of the [MIT license](https://github.com/bradmontgomery/django-querycount/blob/main/LICENSE.txt).
+
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

docs/_src/testing.md

@@ -0,0 +1,8 @@
+# Testing
+
+Run `python manage.py test querycount` to run the tests. Note that this will
+modify your settings so that your project is in DEBUG mode for the duration
+of the `querycount` tests.
+
+**Warning**: this project needs better tests; for the moment, there are only
+smoke tests that set up the middleware and call two simple test views.

docs/html/_sources/configuration.md.txt

@@ -1,3 +1,68 @@
 # Configuration
 
-TBD
+There are two possible settings for this app: The first defines threshold
+values used to color output, while the second allows you customize requests
+that will be ignored by the middleware. The default settings are:
+
+```python
+QUERYCOUNT = {
+    'THRESHOLDS': {
+        'MEDIUM': 50,
+        'HIGH': 200,
+        'MIN_TIME_TO_LOG':0,
+        'MIN_QUERY_COUNT_TO_LOG':0
+    },
+    'IGNORE_REQUEST_PATTERNS': [],
+    'IGNORE_SQL_PATTERNS': [],
+    'DISPLAY_DUPLICATES': None,
+    'RESPONSE_HEADER': 'X-DjangoQueryCount-Count'
+}
+```
+
+The `QUERYCOUNT['THRESHOLDS']` settings will determine how many queries are
+interpreted as high or medium (and the color-coded output). In previous versions
+of this app, this settings was called `QUERYCOUNT_THRESHOLDS` and that setting
+is still supported.
+
+The `QUERYCOUNT['IGNORE_REQUEST_PATTERNS']` setting allows you to define a list of
+regexp patterns that get applied to each request's path. If there is a match,
+the middleware will not be applied to that request. For example, the following
+setting would bypass the querycount middleware for all requests to the admin:
+
+```python
+QUERYCOUNT = {
+    'IGNORE_REQUEST_PATTERNS': [r'^/admin/']
+}
+```
+
+The `QUERYCOUNT['IGNORE_SQL_PATTERNS']` setting allows you to define a list of
+regexp patterns that ignored to statistic sql query count. For example, the following
+setting would bypass the querycount middleware for django-silk sql query:
+
+```python
+QUERYCOUNT = {
+    'IGNORE_SQL_PATTERNS': [r'silk_']
+}
+```
+
+The `QUERYCOUNT['RESPONSE_HEADER']` setting allows you to define a custom response
+header that contains the total number of queries executed. To disable this header,
+the supply `None` as the value:
+
+```python
+QUERYCOUNT = {
+    'RESPONSE_HEADER': None
+}
+```
+
+_New in 0.4.0_. The `QUERYCOUNT['DISPLAY_DUPLICATES']` setting allows you
+to control how the most common duplicate queries are displayed. If the setting
+is `None` (the default), duplicate queries are not displayed. Otherwise, this
+should be an integer. For example, the following setting would always print the
+5 most duplicated queries:
+
+```python
+QUERYCOUNT = {
+    'DISPLAY_DUPLICATES': 5,
+}
+```

docs/html/_sources/contributing.md.txt

@@ -0,0 +1,8 @@
+# Contributing
+
+Bug fixes and new features are welcome!
+
+To contribute, [fork this project](https://github.com/bradmontgomery/django-querycount/),
+and open a Pull Request to have your work included.
+
+Be sure to add yourself to the `AUTHORS.md` file.

docs/html/_sources/index.rst.txt

@@ -1,19 +1,36 @@
 .. django-querycount documentation master file, created by
+   sphinx-quickstart on Tue Dec 13 15:32:52 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
+Welcome to django-querycount's documentation!
+=============================================
 
-Welcome to the django-querycount documentation!
-===============================================
+Inspired by `this post by David Szotten <http://goo.gl/UUKN0r>`_, this project
+gives you a middleware that prints database query counts in Django's runserver
+console output.
+
+|screenshot|
+
+Documentation
+-------------
 
 .. toctree::
-:maxdepth: 2
-:caption: Contents:
+   :maxdepth: 2
+   :caption: Contents:
 
-   Installation <installation.md>
-   Configuration <configuration.md>
+   installation
+   configuration
+   testing
+   contributing
+   license
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`
+
+.. |screenshot| image:: ../screenshot.png
+    :alt: django-querycount in action

docs/html/_sources/installation.md.txt

@@ -1,3 +1,14 @@
 # Installation
 
-TBD
+Install with pip:
+
+```
+pip install django-querycount
+```
+
+Then add `querycount.middleware.QueryCountMiddleware` to your
+`MIDDLEWARE`.
+
+Notice that `django-querycount` only works while your project is in DEBUG mode.
+
+If you must, download a source distribution from [pypi.org/project/django-querycount/](https://pypi.org/project/django-querycount/)

docs/html/_sources/license.md.txt

@@ -0,0 +1,23 @@
+# License
+
+This code is distributed under the terms of the [MIT license](https://github.com/bradmontgomery/django-querycount/blob/main/LICENSE.txt).
+
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

docs/html/_sources/testing.md.txt

@@ -0,0 +1,8 @@
+# Testing
+
+Run `python manage.py test querycount` to run the tests. Note that this will
+modify your settings so that your project is in DEBUG mode for the duration
+of the `querycount` tests.
+
+**Warning**: this project needs better tests; for the moment, there are only
+smoke tests that set up the middleware and call two simple test views.