build docs on CI (#127)

* build docs on ci

* fix docs build

* add numpy

Author: samuelcolvin

.github/workflows/ci.yml

@@ -30,6 +30,26 @@ jobs:
       with:
         extra_args: --all-files --verbose
 
+  docs-build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - run: pip install -r requirements/docs.txt -r requirements/pyproject.txt
+    - run: pip install .
+
+    - run: make docs
+
+    - name: Store docs site
+      uses: actions/upload-artifact@v3
+      with:
+        name: docs
+        path: site
+
   test:
     name: test py${{ matrix.python-version }} on ${{ matrix.os }}
     strategy:
@@ -85,7 +105,7 @@ jobs:
   # https://github.com/marketplace/actions/alls-green#why used for branch protection checks
   check:
     if: always()
-    needs: [test, lint]
+    needs: [test, lint, docs-build]
     runs-on: ubuntu-latest
     steps:
       - name: Decide whether the needed jobs succeeded or failed
@@ -107,6 +127,17 @@ jobs:
         with:
           python-version: '3.10'
 
+      - name: get docs
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: site
+
+      - name: check GITHUB_REF matches package version
+        uses: samuelcolvin/check-python-version@v3
+        with:
+          version_file_path: devtools/version.py
+
       - name: install
         run: pip install build twine
 
@@ -122,6 +153,10 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.pypi_token }}
 
       - name: publish docs
-        run: make publish-docs
+        if: '!fromJSON(steps.check-tag.outputs.IS_PRERELEASE)'
+        uses: cloudflare/[email protected]
+        with:
+          apiToken: ${{ secrets.cloudflare_api_token }}
+          command: pages publish --project-name=python-devtools --branch=main site
         env:
-          NETLIFY: ${{ secrets.netlify_token }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.cloudflare_account_id }}

Makefile

@@ -63,7 +63,7 @@ clean:
 
 .PHONY: docs
 docs:
-	flake8 --max-line-length=80 docs/examples/
+	ruff --line-length=80 docs/examples/
 	mkdocs build
 
 .PHONY: docs-serve

devtools/__init__.py

@@ -1,8 +1,9 @@
-# flake8: noqa
-from .ansi import *
-from .debug import *
-from .prettier import *
-from .timer import *
+from .ansi import sformat, sprint
+from .debug import Debug, debug
+from .prettier import PrettyFormat, pformat, pprint
+from .timer import Timer
 from .version import VERSION
 
 __version__ = VERSION
+
+__all__ = 'sformat', 'sprint', 'Debug', 'debug', 'PrettyFormat', 'pformat', 'pprint', 'Timer', 'VERSION'

docs/examples/ansi_colours.py

@@ -1,4 +1,4 @@
-from devtools import sprint, sformat
+from devtools import sformat, sprint
 
 sprint('this is red', sprint.red)
 

docs/examples/complex.py

@@ -1,6 +1,7 @@
-from devtools import debug
 import numpy as np
 
+from devtools import debug
+
 foo = {
     'foo': np.array(range(20)),
     'bar': [{'a': i, 'b': {j for j in range(1 + i * 2)}} for i in range(3)],

docs/examples/other.py

@@ -20,7 +20,7 @@
 # if used repeatedly a summary is available
 t3 = debug.timer()
 for i in [1e4, 1e6, 1e7]:
-    with t3('sum {}'.format(i), verbose=False):
+    with t3(f'sum {i}', verbose=False):
         sum(range(int(i)))
 
 t3.summary(verbose=True)

docs/examples/prettier.py

@@ -1,6 +1,7 @@
-from devtools import PrettyFormat, pprint, pformat
 import numpy as np
 
+from devtools import PrettyFormat, pformat, pprint
+
 v = {
     'foo': {'whatever': [3, 2, 1]},
     'sentence': 'hello\nworld',

requirements/docs.in

@@ -1,7 +1,9 @@
-ansi2html==1.8.0
-mkdocs==1.3.1
-mkdocs-exclude==1.0.2
-mkdocs-material==8.3.9
-mkdocs-simple-hooks==0.1.5
-markdown-include==0.7.0
+ansi2html
+mkdocs
+mkdocs-exclude
+mkdocs-material
+mkdocs-simple-hooks
+markdown-include
 pygments
+ruff
+numpy

requirements/docs.txt

@@ -6,12 +6,18 @@
 #
 ansi2html==1.8.0
     # via -r requirements/docs.in
+certifi==2022.12.7
+    # via requests
+charset-normalizer==3.1.0
+    # via requests
 click==8.1.3
     # via mkdocs
+colorama==0.4.6
+    # via mkdocs-material
 ghp-import==2.1.0
     # via mkdocs
-importlib-metadata==6.1.0
-    # via mkdocs
+idna==3.4
+    # via requests
 jinja2==3.1.2
     # via
     #   mkdocs
@@ -22,26 +28,28 @@ markdown==3.3.7
     #   mkdocs
     #   mkdocs-material
     #   pymdown-extensions
-markdown-include==0.7.0
+markdown-include==0.8.1
     # via -r requirements/docs.in
 markupsafe==2.1.2
     # via jinja2
 mergedeep==1.3.4
     # via mkdocs
-mkdocs==1.3.1
+mkdocs==1.4.2
     # via
     #   -r requirements/docs.in
     #   mkdocs-exclude
     #   mkdocs-material
     #   mkdocs-simple-hooks
 mkdocs-exclude==1.0.2
     # via -r requirements/docs.in
-mkdocs-material==8.3.9
+mkdocs-material==9.1.5
     # via -r requirements/docs.in
 mkdocs-material-extensions==1.1.1
     # via mkdocs-material
 mkdocs-simple-hooks==0.1.5
     # via -r requirements/docs.in
+numpy==1.24.2
+    # via -r requirements/docs.in
 packaging==23.0
     # via mkdocs
 pygments==2.14.0
@@ -59,9 +67,15 @@ pyyaml==6.0
     #   pyyaml-env-tag
 pyyaml-env-tag==0.1
     # via mkdocs
+regex==2023.3.23
+    # via mkdocs-material
+requests==2.28.2
+    # via mkdocs-material
+ruff==0.0.261
+    # via -r requirements/docs.in
 six==1.16.0
     # via python-dateutil
+urllib3==1.26.15
+    # via requests
 watchdog==3.0.0
     # via mkdocs
-zipp==3.15.0
-    # via importlib-metadata