README.md

@@ -1,10 +1,6 @@
 # Blender Asset Tracer BAT🦇
 
-Script to manage assets with Blender.
+Blender Asset Tracer, a.k.a. BAT🦇 is a script to manage assets with Blender.
-
-Blender Asset Tracer, a.k.a. BAT🦇, is the replacement of
-[BAM](https://developer.blender.org/diffusion/BAM/) and
-[blender-file](https://developer.blender.org/source/blender-file/)
 
 Development is driven by choices explained in [T54125](https://developer.blender.org/T54125).
 
@@ -13,18 +9,28 @@ Development is driven by choices explained in [T54125](https://developer.blender
 The `cli.py` wrapper at the root of the project can be used to directly access the command line
 tools, without requiring any setup involving `venv` and so on:
 
-```
+```bash
 python3 path/to/repo/cli.py list path/to/blendfile.blend
 ```
 
 ## Setting up development environment
 
-```
+```bash
 python3.9 -m venv .venv
+```
+```bash
 . ./.venv/bin/activate
+```
+```bash
 pip install -U pip
+```
+```bash
 pip install poetry black
+```
+```bash
 poetry install
+```
+```bash
 mypy --install-types
 ```
 
@@ -34,14 +40,18 @@ mypy --install-types
 BAT Pack supports uploading to S3-compatible storage. This requires a credentials file in
 `~/.aws/credentials`. Replace the all-capital words to suit your situation.
 
-    [ENDPOINT]
+```ini
-    aws_access_key_id = YOUR_ACCESS_KEY_ID
+[ENDPOINT]
-    aws_secret_access_key = YOUR_SECRET
+aws_access_key_id = YOUR_ACCESS_KEY_ID
+aws_secret_access_key = YOUR_SECRET
+```
 
 You can then send a BAT Pack to the storage using a target `s3:/ENDPOINT/bucketname/path-in-bucket`,
 for example:
 
-    bat pack my_blendfile.blend s3:/storage.service.cloud/jobs/awesome_work
+```bash
+bat pack my_blendfile.blend s3:/storage.service.cloud/jobs/awesome_work
+```
 
 This will upload the blend file and its dependencies to `awesome_work/my_blendfile.blend` in
 the `jobs` bucket.
@@ -76,49 +86,51 @@ Mypy likes to see the return type of `__init__` methods explicitly declared as `
 BAT can be used as a Python library to inspect the contents of blend files, without having to
 open Blender itself. Here is an example showing how to determine the render engine used:
 
-    #!/usr/bin/env python3.7
+```python
-    import json
+#!/usr/bin/env python3.7
-    import sys
+import json
-    from pathlib import Path
+import sys
+from pathlib import Path
 
-    from blender_asset_tracer import blendfile
+from blender_asset_tracer import blendfile
-    from blender_asset_tracer.blendfile import iterators
+from blender_asset_tracer.blendfile import iterators
 
-    if len(sys.argv) != 2:
+if len(sys.argv) != 2:
-        print(f'Usage: {sys.argv[0]} somefile.blend', file=sys.stderr)
+    print(f'Usage: {sys.argv[0]} somefile.blend', file=sys.stderr)
-        sys.exit(1)
+    sys.exit(1)
 
-    bf_path = Path(sys.argv[1])
+bf_path = Path(sys.argv[1])
-    bf = blendfile.open_cached(bf_path)
+bf = blendfile.open_cached(bf_path)
 
-    # Get the first window manager (there is probably exactly one).
+# Get the first window manager (there is probably exactly one).
-    window_managers = bf.find_blocks_from_code(b'WM')
+window_managers = bf.find_blocks_from_code(b'WM')
-    assert window_managers, 'The Blend file has no window manager'
+assert window_managers, 'The Blend file has no window manager'
-    window_manager = window_managers[0]
+window_manager = window_managers[0]
 
-    # Get the scene from the first window.
+# Get the scene from the first window.
-    windows = window_manager.get_pointer((b'windows', b'first'))
+windows = window_manager.get_pointer((b'windows', b'first'))
-    for window in iterators.listbase(windows):
+for window in iterators.listbase(windows):
-        scene = window.get_pointer(b'scene')
+    scene = window.get_pointer(b'scene')
-        break
+    break
 
-    # BAT can only return simple values, so it can't return the embedded
+# BAT can only return simple values, so it can't return the embedded
-    # struct 'r'. 'r.engine' is a simple string, though.
+# struct 'r'. 'r.engine' is a simple string, though.
-    engine = scene[b'r', b'engine'].decode('utf8')
+engine = scene[b'r', b'engine'].decode('utf8')
-    xsch = scene[b'r', b'xsch']
+xsch = scene[b'r', b'xsch']
-    ysch = scene[b'r', b'ysch']
+ysch = scene[b'r', b'ysch']
-    size = scene[b'r', b'size'] / 100.0
+size = scene[b'r', b'size'] / 100.0
 
-    render_info = {
+render_info = {
-        'engine': engine,
+    'engine': engine,
-        'frame_pixels': {
+    'frame_pixels': {
-            'x': int(xsch * size),
+        'x': int(xsch * size),
-            'y': int(ysch * size),
+        'y': int(ysch * size),
-        },
+    },
-    }
+}
 
-    json.dump(render_info, sys.stdout, indent=4, sort_keys=True)
+json.dump(render_info, sys.stdout, indent=4, sort_keys=True)
-    print()
+print()
+```
 
 To understand the naming of the properties, look at Blender's `DNA_xxxx.h` files with struct
 definitions. It is those names that are accessed via `blender_asset_tracer.blendfile`. The
@@ -155,23 +167,29 @@ As password, use the token itself, including the `pypi-` prefix.
 See https://pypi.org/help/#apitoken for help using API tokens to publish. This
 is what I have in `~/.pypirc`:
 
-```
+```ini
 [distutils]
-index-servers =
+index-servers = bat
-    bat
 
 # Use `twine upload -r bat` to upload with this token.
 [bat]
-  repository = https://upload.pypi.org/legacy/
+repository = https://upload.pypi.org/legacy/
-  username = __token__
+username = __token__
-  password = pypi-abc-123-blablabla
+password = pypi-abc-123-blablabla
 ```
 
-```
+```bash
 . ./.venv/bin/activate
+```
+```bash
 pip install twine
-
+```
+```bash
 poetry build
+```
+```bash
 twine check dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl
+```
+```bash
 twine upload -r bat dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl
 ```