autour_de_minuit/blender-asset-tracer
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Written some documentation with Sphinx

Browse Source
This commit is contained in:
Sybren A. Stüvel 2018-03-22 11:01:20 +01:00
parent 8b73b86734
commit 08ed33ef81
11 changed files with 555 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -11,3 +11,5 @@ __pycache__
/tests/blendfiles/cache_ocean/
/tests/blendfiles/T53562/blendcache_bam_pack_bug/
/docs/_build

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = BlenderAssetTracer
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

85
docs/cli.rst Normal file
View File

@ -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`.

167
docs/conf.py Normal file
View File

@ -0,0 +1,167 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/stable/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Blender Asset Tracer'
copyright = '2018, Sybren A. Stüvel'
author = 'Sybren A. Stüvel'
# The short X.Y version
version = '0.2-dev'
# The full version, including alpha/beta/rc tags
release = '0.2-dev'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.coverage',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'BlenderAssetTracerdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'BlenderAssetTracer.tex', 'Blender Asset Tracer Documentation',
'Sybren A. Stüvel', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'blenderassettracer', 'Blender Asset Tracer Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'BlenderAssetTracer', 'Blender Asset Tracer Documentation',
author, 'BlenderAssetTracer', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

35
docs/index.rst Normal file
View File

@ -0,0 +1,35 @@
.. Blender Asset Tracer documentation master file, created by
sphinx-quickstart on Thu Mar 22 11:00:50 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Blender Asset Tracer's documentation!
================================================
Blender Asset Tracer, a.k.a. BAT🦇, is the replacement of BAM_ and
blender-file_. BAT🦇 can be used to list all dependencies of a blend file, such
as linked blend files, textures, Alembic files, and caches. Furthermore, it can
be used to create a BAT Pack (see :ref:`packing`), which contains the blend file
and its dependencies.
.. _BAM: https://developer.blender.org/diffusion/BAM/
.. _blender-file: https://developer.blender.org/source/blender-file/
.. toctree::
:maxdepth: 2
:caption: Contents:
installation
packing
cli
license
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

35
docs/installation.rst Normal file
View File

@ -0,0 +1,35 @@
Installation
============
BAT🦇 can be installed with `pip`::
pip install blender-asset-tracer
Requirements and Dependencies
-----------------------------
In order to run BAT you need Python 3.5; BAT always targets the Python version
used in the `latest Blender release`_.
.. _`latest Blender release`: https://www.blender.org/download
Apart from Python, BAT has very little external dependencies. When only working
with the local filesystem (which includes network shares; anything that your
computer can simply copy files to) it has no extra dependencies. Uploading to
S3-compatible storage requires the `boto3` library.
Development dependencies
------------------------
In order to start developing on BAT you need a bit more. First use Git_ to get a
copy of the source::
git clone https://gitlab.com/dr.sybren/blender-asset-tracer.git
virtualenv -p /path/to/python3 bat-venv
. ./bat-venv/bin/activate
cd blender-asset-tracer
pip3 install -U -r requirements-dev.txt
.. _Git: https://git-scm.com/

49
docs/license.rst Normal file
View File

@ -0,0 +1,49 @@
Licence
=======
This section describes the licenses for both the software and the documentation.
Software
--------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Documentation
-------------
This documentation is covered by the `Creative Commons BY-SA 4.0 license`_.
.. _`Creative Commons BY-SA 4.0 license`: https://creativecommons.org/licenses/by-sa/4.0/
This is a human-readable summary of (and not a substitute for) the license.
Disclaimer. You are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material for any purpose,
even commercially.
Under the following terms:
- Attribution — You must give appropriate credit, provide a link to the
license, and indicate if changes were made. You may do so in any
reasonable manner, but not in any way that suggests the licensor endorses
you or your use.
- ShareAlike — If you remix, transform, or build upon the material, you must
distribute your contributions under the same license as the original.
No additional restrictions — You may not apply legal terms or technological
measures that legally restrict others from doing anything the license permits.

36
docs/make.bat Normal file
View File

@ -0,0 +1,36 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
set SPHINXPROJ=BlenderAssetTracer
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

118
docs/packing.rst Normal file
View File

@ -0,0 +1,118 @@
.. _packing:
Packing
=======
BAT can create BAT Packs. These packs take the form of a directory or a ZIP
file, and contain a blend file together with its dependencies, such as linked
blend files, textures, fonts, Alembic files, and caches.
The blend file is inspected relative to a *project directory*. This allows BAT
to mimick the project structure as well as possible. For example, a typical
Blender Animation Studio project looks something like this::
/path/to/agent327
├── lib
│   ├── chars
│   │   ├── agent.blend
│   │   ├── barber.blend
│   │   ├── boris.blend
│   ├── envs
│   │   ├── barbershop_exterior.blend
│   │   ├── barbershop_interior.blend
│   │   └── elevator_shaft.blend
│   ├── maps
│   │   ├── lots-of-textures.png
│   │   └── lots-of-textures.jpg
│   ├── nodes
│   └── props
│   └── shaving_cream_brush.blend
└── scenes
   ├── 01-opening
   │   ├── 01_01_B-city_tilt
   │   ├── 01_02_A-barbershop_ext
   │   └── 01_04_B-watch
   └── 02-boris
      └── 02_01_A-car_enter
Of course this is a simplified view, but it serves the purpose of this
documentation. A BAT Pack for the Agent 327 model would include the
``agent.blend`` file and its textures from the ``maps`` folder. To create the
BAT Pack, use the following command::
cd /path/to/agent327
bat pack -p . lib/chars/agent.blend /path/to/agent-pack
This will create the ``/path/to/agent-pack`` directory and place the following
files there::
/path/to/agent-pack
├── lib
│   ├── chars
│   │   ├── agent.blend
│   │   └── maps
│   │   ├── agent_eyes_color.png
│   │   ├── agent_face_bruises_color.png
│   │   ├── agent_face_bump.png
│   │   ├── agent_face_color.png
│   │   ├── agent_face_spec.png
│   │   ├── agent_hair_mask_cut.png
│   │   ├── agent_hair_mask.png
│   │   ├── agent_hands_bump.png
│   │   ├── agent_hands_color.png
│   │   ├── agent_hands_spec.png
│   │   ├── agent_pattern_suit.jpg
│   │   ├── agent_shoes_color.png
│   │   ├── agent_shoes_leather.png
│   │   ├── agent_suit_bump.png
│   │   ├── agent_suit_color.png
│   │   ├── agent_suit_disp_bend.png
│   │   ├── agent_suit_disp_scratch.png
│   │   ├── agent_suit_disp_stretch.png
│   │   ├── barber_jacket_pattern.jpg
│   │   ├── pattern2_jacket_color.png
│   │   └── pattern2_jacket_normal.png
│   ├── maps
│   │   ├── barbershop_env_reflection.exr
│   │   ├── brushes
│   │   │   └── stitch_64.png
│   │   ├── grunge_scratches_generic.png
│   │   ├── grunge_worn_drag_scratches.png-color.png
│   │   └── metal_painted02_spec_tileable.png-specular.png
│   └── props
│   └── maps
│   └── fabric_leather_bright01_col_tileable.png
└── pack-info.txt
The ``pack-info.txt`` file is created by BAT and describes that this is a BAT
Pack for ``lib/chars/agent.blend``.
Out-of-project files
--------------------
Any files that are linked from outside the project will be placed in a special
directory ``_outside_project`` in the BAT Pack. This causes file links to
change. Let's say you want to pack a blend file
``/home/you/project/file.blend``, which uses
``/home/you/pictures/backdrop.jpg``. This will create the following BAT Pack::
/path/to/agent-pack
├── file.blend
├── _outside_project
│   └── home
│      └── you
│      └── pictures
│      └── backdrop.jpg
└── pack-info.txt
The ``file.blend`` will be rewritten so that it refers to the ``backdrop.jpg``
inside the BAT pack, using a relative path. In this sense, the BAT Pack is a
"portable" version of the blend file.
ZIP files
---------
BAT can pack to a ZIP file, simply by ending the target name with ``.zip``::
bat pack file.blend /path/to/packed-file.zip

5
requirements-dev.txt
View File

@ -5,3 +5,8 @@ pytest
pytest-cov
radon # for the 'radon cc' command
pyprof2calltree # for converting profiler output to KCacheGrind input
# For documentation
sphinx
sphinx-autobuild
sphinx_rtd_theme

4
update_version.sh
View File

@ -6,10 +6,12 @@ if [ -z "$1" ]; then
fi
sed "s/version='[^']*'/version='$1'/" -i setup.py
sed "s/version = '[^']*'/version = '$1'/" -i docs/conf.py
sed "s/release = '[^']*'/release = '$1'/" -i docs/conf.py
sed "s/__version__\s*=\s*'[^']*'/__version__ = '$1'/" -i blender_asset_tracer/__init__.py
git diff
echo
echo "Don't forget to commit and tag:"
echo git commit -m \'Bumped version to $1\' setup.py blender_asset_tracer/__init__.py
echo git commit -m \'Bumped version to $1\' setup.py blender_asset_tracer/__init__.py docs/conf.py
echo git tag -a v$1 -m \'Tagged version $1\'