README.md

@@ -1,6 +1,10 @@
 # Blender Asset Tracer BAT🦇
 
-Blender Asset Tracer, a.k.a. BAT🦇 is a script to manage assets with Blender.
+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).
 
@@ -9,28 +13,18 @@ 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
 ```
 
@@ -40,18 +34,14 @@ 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.
 
-```ini
+    [ENDPOINT]
-[ENDPOINT]
+    aws_access_key_id = YOUR_ACCESS_KEY_ID
-aws_access_key_id = YOUR_ACCESS_KEY_ID
+    aws_secret_access_key = YOUR_SECRET
-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:
 
-```bash
+    bat pack my_blendfile.blend s3:/storage.service.cloud/jobs/awesome_work
-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.
@@ -86,51 +76,49 @@ 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:
 
-```python
+    #!/usr/bin/env python3.7
-#!/usr/bin/env python3.7
+    import json
-import json
+    import sys
-import sys
+    from pathlib import Path
-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
@@ -167,29 +155,23 @@ 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 = bat
+index-servers =
+    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
 ```