Written some documentation with Sphinx

2018-03-22 12:12:30 +01:00
parent 8b73b86734
commit 08ed33ef81
11 changed files with 555 additions and 1 deletions
@@ -0,0 +1,85 @@
+Commandline usage
+=================
+
+After installation_, ``bat --help`` will show you general usage instructions.
+The command structure is::
+
+    bat [common options] {subcommand} [subcommand-specific options]
+
+The common options are all optional::
+
+  -p, --profile  Run the profiler, write to bam.prof
+  -v, --verbose  Log INFO level and higher
+  -d, --debug    Log everything
+  -q, --quiet    Log at ERROR level and higher
+
+For most users only ``--verbose`` is useful, the other options can be very
+helpful during development or debugging.
+
+Logging is sent to ``stderr``, whereas regular output is sent to ``stdout``.
+
+The available subcommands are described in the next sections. Each subcommand
+also takes a ``--help`` argument to get specific usage instructions.
+
+
+List
+----
+
+The ``bat list`` command lists the dependencies of a blend file. When there are
+no dependencies, it outputs nothing. Example::
+
+    % bat list tests/blendfiles/doubly_linked.blend
+    tests/blendfiles/doubly_linked.blend
+        tests/blendfiles/linked_cube.blend
+        tests/blendfiles/material_textures.blend
+    tests/blendfiles/linked_cube.blend
+        tests/blendfiles/basic_file.blend
+    tests/blendfiles/material_textures.blend
+        tests/blendfiles/textures/Bricks/brick_dotted_04-bump.jpg
+        tests/blendfiles/textures/Bricks/brick_dotted_04-color.jpg
+
+By passing the ``--json`` option it outputs to JSON rather than plain text::
+
+    {
+        "/path/to/blender-asset-tracer/tests/blendfiles/material_textures.blend": [
+            "/path/to/blender-asset-tracer/tests/blendfiles/textures/Bricks/brick_dotted_04-bump.jpg",
+            "/path/to/blender-asset-tracer/tests/blendfiles/textures/Bricks/brick_dotted_04-color.jpg"
+        ],
+        "/path/to/blender-asset-tracer/tests/blendfiles/linked_cube.blend": [
+            "/path/to/blender-asset-tracer/tests/blendfiles/basic_file.blend"
+        ],
+        "/path/to/blender-asset-tracer/tests/blendfiles/doubly_linked.blend": [
+            "/path/to/blender-asset-tracer/tests/blendfiles/linked_cube.blend",
+            "/path/to/blender-asset-tracer/tests/blendfiles/material_textures.blend"
+        ]
+    }
+
+Note that in this case all paths are absolute, whereas the regular output shows
+paths relative to the current working directory.
+
+
+Pack
+----
+
+The ``bat pack`` command takes the dependencies as shown by ``bat list`` and
+copies them to a target. This target can be a directory, a ZIP file, or
+S3-compatible storage::
+
+    bat pack [-h] [-p PROJECT] [-n] [-e [EXCLUDEs] blendfile target
+
+The optional arguments influence the manner of packing::
+
+      -p PROJECT, --project PROJECT
+                            Root directory of your project. Paths to below this
+                            directory are kept in the BAT Pack as well, whereas
+                            references to assets from outside this directory will
+                            have to be rewitten. The blend file MUST be inside the
+                            project directory. If this option is ommitted, the
+                            directory containing the blend file is taken as the
+                            project directoy.
+      -n, --noop            Don't copy files, just show what would be done.
+      -e [EXCLUDEs, --exclude [EXCLUDEs]
+                            Space-separated list of glob patterns (like '*.abc')
+                            to exclude.
+
+For more information see the chapter :ref:`packing`.