Docs improvements (#66)

* moving from rst to md

* switching docs to mkdocs

* fix linting in examples

* working on usage

* fixing mkdocs site

* rename examples to make more sense, formatting

* more customisation

* try deploy step

* fix ci

Author: samuelcolvin

.github/workflows/ci.yml

@@ -99,3 +99,8 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.pypi_token }}
+
+      - name: publish docs
+        run: make publish-docs
+        env:
+          NETLIFY: ${{ secrets.netlify_token }}

.gitignore

@@ -5,7 +5,6 @@ env36/
 env37/
 *.py[cod]
 *.egg-info/
-build/
 dist/
 .cache/
 .mypy_cache/
@@ -14,6 +13,8 @@ test.py
 htmlcov/
 benchmarks/*.json
 docs/_build/
+/docs/.*.md
 docs/examples/*.html
 old-version/
 *.swp
+/site/

HISTORY.md

@@ -0,0 +1,31 @@
+## v0.6.0 (2020-07-29)
+* improve `__pretty__` to work better with pydantic classes, #52
+* improve the way statement ranges are calculated, #58
+* drastically improve import time, #50
+* pretty printing for non-standard dicts, #60
+* better statement finding for multi-line statements, #61
+* colors in windows, #57
+* fix `debug(type(dict(...)))`, #62
+
+## v0.5.1 (2019-10-09)
+* fix python tag in `setup.cfg`, #46
+
+## v0.5.0 (2019-01-03)
+* support `MultiDict`, #34
+* support `__pretty__` method, #36
+
+## v0.4.0 (2018-12-29)
+* remove use of `warnings`, include in output, #30
+* fix rendering errors #31
+* better str and bytes wrapping #32
+* add `len` everywhere possible, part of #16
+
+## v0.3.0 (2017-10-11)
+* allow `async/await` arguments
+* fix subscript
+* fix weird named tuples eg. `mock > call_args`
+* add `timer`
+
+## v0.2.0 (2017-09-14)
+* improve output
+* numerous bug fixes

HISTORY.rst

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include HISTORY.md

MANIFEST.in

@@ -55,11 +55,17 @@ clean:
 
 .PHONY: docs
 docs:
-	make -C docs html
+	flake8 --max-line-length=80 docs/examples/
+	python docs/build/main.py
+	mkdocs build
 
-.PHONY: publish
-publish: docs
-	cd docs/_build/ && cp -r html site && zip -r site.zip site
-	@curl -i -H "Content-Type: application/zip" -H "Authorization: Bearer ${NETLIFY}" \
-	      --data-binary "@docs/_build/site.zip" https://api.netlify.com/api/v1/sites/python-devtools.netlify.com/deploys
-	@echo " "
+.PHONY: docs-serve
+docs-serve:
+	python docs/build/main.py
+	mkdocs serve
+
+.PHONY: publish-docs
+publish-docs: docs
+	zip -r site.zip site
+	@curl -H "Content-Type: application/zip" -H "Authorization: Bearer ${NETLIFY}" \
+	      --data-binary "@site.zip" https://api.netlify.com/api/v1/sites/python-devtools.netlify.com/deploys

Makefile

@@ -0,0 +1,74 @@
+# python devtools
+
+[![CI](https://github.com/samuelcolvin/python-devtools/workflows/CI/badge.svg?event=push)](https://github.com/samuelcolvin/python-devtools/actions?query=event%3Apush+branch%3Amaster+workflow%3ACI)
+[![Coverage](https://codecov.io/gh/samuelcolvin/python-devtools/branch/master/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/python-devtools)
+[![pypi](https://img.shields.io/pypi/v/python-devtools.svg)](https://pypi.python.org/pypi/python-devtools)
+[![versions](https://img.shields.io/pypi/pyversions/python-devtools.svg)](https://github.com/samuelcolvin/python-devtools)
+[![license](https://img.shields.io/github/license/samuelcolvin/python-devtools.svg)](https://github.com/samuelcolvin/python-devtools/blob/master/LICENSE)
+
+**Python's missing debug print command and other development tools.**
+
+For more information, see [documentation](https://python-devtools.helpmanual.io/).
+
+## Install
+
+Just
+
+```bash
+pip install devtools[pygments]
+```
+
+`pygments` is not required but if it's installed, output will be highlighted and easier to read.
+
+`devtools` has no other required dependencies except python 3.6, 3.7, or 3.8.
+If you've got python 3.6+ and `pip` installed, you're good to go.
+
+## Usage
+
+```py
+from devtools import debug
+
+whatever = [1, 2, 3]
+debug(whatever)
+```
+
+Outputs:
+
+```py
+test.py:4 <module>:
+    whatever: [1, 2, 3] (list)
+```
+
+
+That's only the tip of the iceberg, for example:
+
+```py
+import numpy as np
+
+data = {
+    'foo': np.array(range(20)),
+    'bar': {'apple', 'banana', 'carrot', 'grapefruit'},
+    'spam': [{'a': i, 'b': (i for i in range(3))} for i in range(3)],
+    'sentence': 'this is just a boring sentence.\n' * 4
+}
+
+debug(data)
+```
+
+outputs:
+
+![python-devtools demo](https://raw.githubusercontent.com/samuelcolvin/python-devtools/master/demo.py.png)
+
+## Usage without Import
+
+modify `/usr/lib/python3.8/sitecustomize.py` making `debug` available in any python 3.8 code
+
+```py
+# add devtools debug to builtins
+try:
+    from devtools import debug
+except ImportError:
+    pass
+else:
+    __builtins__['debug'] = debug
+```