mirror of https://github.com/wanadev/yoga.git
Updates CONTRIBUTING doc (closes #31)
This commit is contained in:
Fabien LOISON
parent
8f4d1de706
commit
160cc4cf56
|
|
@ -12,7 +12,7 @@ YOGA - Yummy Optimizer for Gorgeous Assets
|
|||
* convert and optimize 3D models from various formats to `glTF and GLB`_.
|
||||
|
||||
**Images** are opened using Pillow_ and optimized using Guetzli_ (for JPEGs),
|
||||
Zopflipng_ (for PNGs) and libwebp_ (for WEBP).
|
||||
Zopflipng_ (for PNGs) and libwebp_ (for WEBPs).
|
||||
|
||||
**3D Models** are converted and optimized using assimp_. If models contain or
|
||||
reference images, they are processed by YOGA's image optimizer.
|
||||
|
|
|
|||
|
|
@ -36,52 +36,180 @@ best way to do it. This is, of course, not necessary if you just want to fix
|
|||
some typo in the documentation or small errors in the code.
|
||||
|
||||
Please note that your code must pass tests and follow the coding style defined
|
||||
by the `pep8 <https://pep8.org/>`_.
|
||||
by the `pep8 <https://pep8.org/>`_. The code of this project is automatically
|
||||
checked by Flake8_ and the coding style is enforced using Black_.
|
||||
|
||||
|
||||
Installing Development Dependencies
|
||||
-----------------------------------
|
||||
Developing YOGA
|
||||
---------------
|
||||
|
||||
You can install YOGA with its development dependencies using the following
|
||||
command::
|
||||
If you want to contribute to the YOGA development, you will find here all
|
||||
useful information to start. Please note that this guide assume you are using
|
||||
Linux as operating system and a POSIX shell (like Bash or ZSH).
|
||||
|
||||
pip install .[dev]
|
||||
Programming languages used in this project:
|
||||
|
||||
* Python_ (2.7, 3.7, 3.8 and 3.9)
|
||||
* C++
|
||||
|
||||
Libraries:
|
||||
|
||||
* CFFI_: C/Python binding
|
||||
* Pillow_: Image processing library
|
||||
* PyGuetzli_: JPEG optimization
|
||||
* ZopfliPy_: PNG Optimization
|
||||
|
||||
Development tools:
|
||||
|
||||
* Black_: Code formater
|
||||
* Flake8_: Linter
|
||||
* Pytest_: Unit test
|
||||
|
||||
Documentation:
|
||||
|
||||
* Sphinx_: Static documentation generator
|
||||
|
||||
Installing Prerequisite
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**On Linux**, you will need to install Python, cmake and the GCC toolchain to
|
||||
build the C++ part of YOGA. On Debian / Ubuntu, this can be achieved with the
|
||||
following command::
|
||||
|
||||
sudo apt install build-essential cmake python3 python3-dev python3-pip python3-venv python-setuptools
|
||||
|
||||
**On Windows** you will need to install Python, cmake and Visual Studio Build
|
||||
Tools (MSVC and MSBuild) and have them available in your PATH. You may find some more information in the ``winbuild/`` folder of the YOGA repository:
|
||||
|
||||
* https://github.com/wanadev/yoga/tree/master/winbuild
|
||||
|
||||
|
||||
Running the Tests
|
||||
-----------------
|
||||
Creating a Virtualenv
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You will first have to install `nox <https://nox.thea.codes/>`_::
|
||||
While not mandatory, using a *virtualenv* is **highly recommended** to avoid
|
||||
installing dependencies everywhere on your system and to ensure using the right
|
||||
version of the dependencies.
|
||||
|
||||
pip3 install nox
|
||||
To create the *virtualenv*, you can use the following command::
|
||||
|
||||
Then you can check for lint error::
|
||||
python3 -m venv __env__
|
||||
|
||||
nox --session lint
|
||||
This should create a ``__env__/`` folder in the current directory. This is where dependencies will be installed.
|
||||
|
||||
or run the tests::
|
||||
Once the *virtualenv* created, you have to activate it with the following command::
|
||||
|
||||
nox --session test
|
||||
source __env__/bin/activate
|
||||
|
||||
This should prefix your prompt with ``(__env__)``.
|
||||
|
||||
To leave the *virtualenv*, just type the following command::
|
||||
|
||||
deactivate
|
||||
|
||||
If you want to go back in the *virtualenv*, you will only need to execute the
|
||||
``"source __env__/bin/activate"`` command again.
|
||||
|
||||
|
||||
Installing the Python Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To install the development dependencies, just run the following command (with
|
||||
your *virtualenv* activated)::
|
||||
|
||||
pip install -r requirements.dev.txt
|
||||
|
||||
|
||||
Building the C++ Part of YOGA
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Building Assimp
|
||||
"""""""""""""""
|
||||
|
||||
You will first need to build *assimp*, the library used by YOGA to handle 3D
|
||||
models. This can be done with the following command (with your *virtualenv*
|
||||
activated)::
|
||||
|
||||
python setup.py build
|
||||
|
||||
.. NOTE::
|
||||
|
||||
You will not need to run this command again, until you make some
|
||||
modification in the Assmimp sources (``assimp/`` folder).
|
||||
|
||||
Building the YOGA C++ module
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
To build the YOGA C++ module, run the following command (with your *virtualenv*
|
||||
activated)::
|
||||
|
||||
python yoga/model/assimp_build.py
|
||||
|
||||
This will generate a ``.so`` file (for Linux; on Windows this will be
|
||||
a ``.pyd`` file instead) in the ``yoga/model/`` folder.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
You will not need to run this command again, until you modify the
|
||||
``yoga/model/assimp.cpp`` and ``yoga/model/assimp.h`` files.
|
||||
|
||||
|
||||
Linting and Testing
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can check for lint and coding style errors with the following command::
|
||||
|
||||
nox -s lint
|
||||
|
||||
If Black reports you coding style errors, you can automatically fix them with
|
||||
this command::
|
||||
|
||||
nox -s black_fix
|
||||
|
||||
To run the tests use::
|
||||
|
||||
nox -s test
|
||||
|
||||
To run the tests only for a specific Python version, you can use following
|
||||
commands (the corresponding Python interpreter must be installed on your
|
||||
machine)::
|
||||
|
||||
nox --session test-2.7
|
||||
nox --session test-3.5
|
||||
nox --session test-3.6
|
||||
nox --session test-3.7
|
||||
nox --session test-3.8
|
||||
nox --session test-3.9
|
||||
nox -s test-2.7
|
||||
nox -s test-3.7
|
||||
nox -s test-3.8
|
||||
nox -s test-3.9
|
||||
|
||||
YOGA tests are very slow to run (especially the ones related to the image
|
||||
optimization). If you want to run only specific tests, you can run them using
|
||||
pytest_::
|
||||
|
||||
pytest -v test/specific_test_file.py
|
||||
|
||||
|
||||
|
||||
Building the Documentation
|
||||
--------------------------
|
||||
|
||||
This documentation is build using Sphinx_.
|
||||
|
||||
You will first have to install `nox <https://nox.thea.codes/>`_::
|
||||
|
||||
pip3 install nox
|
||||
|
||||
Then you can run the following command::
|
||||
|
||||
nox --session gendoc
|
||||
nox -s gendoc
|
||||
|
||||
|
||||
.. _Python: https://www.python.org/
|
||||
|
||||
.. _CFFI: https://cffi.readthedocs.io/en/latest/
|
||||
.. _Pillow: https://pillow.readthedocs.io/en/stable/
|
||||
.. _PyGuetzli: https://github.com/wanadev/pyguetzli
|
||||
.. _ZopfliPy: https://github.com/hattya/zopflipy
|
||||
|
||||
.. _Flake8: https://flake8.pycqa.org/en/latest/
|
||||
.. _Black: https://black.readthedocs.io/en/stable/
|
||||
.. _pytest: https://docs.pytest.org/
|
||||
|
||||
.. _Sphinx: https://www.sphinx-doc.org/en/master/
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Welcome to YOGA's documentation!
|
|||
* convert and optimize 3D models from various formats to `glTF and GLB`_.
|
||||
|
||||
**Images** are opened using Pillow_ and optimized using Guetzli_ (for JPEGs),
|
||||
Zopflipng_ (for PNGs) and libwebp_ (for WEBP).
|
||||
Zopflipng_ (for PNGs) and libwebp_ (for WEBPs).
|
||||
|
||||
**3D Models** are converted and optimized using assimp_. If models contain or
|
||||
reference images, they are processed by YOGA's image optimizer.
|
||||
|
|
|
|||
|
|
@ -23,6 +23,12 @@ def lint(session):
|
|||
)
|
||||
|
||||
|
||||
@nox.session(reuse_venv=True)
|
||||
def black_fix(session):
|
||||
session.install("black")
|
||||
session.run("black", *PYTHON_FILES)
|
||||
|
||||
|
||||
@nox.session(python=["2.7", "3.7", "3.8", "3.9"], reuse_venv=True)
|
||||
def test(session):
|
||||
session.install("pytest")
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
-r requirements.txt
|
||||
alabaster==0.7.12
|
||||
appdirs==1.4.4
|
||||
argcomplete==1.12.2
|
||||
attrs==20.3.0
|
||||
Babel==2.9.0
|
||||
certifi==2020.12.5
|
||||
chardet==4.0.0
|
||||
colorlog==4.8.0
|
||||
distlib==0.3.1
|
||||
docutils==0.16
|
||||
filelock==3.0.12
|
||||
flake8==3.9.1
|
||||
idna==2.10
|
||||
imagesize==1.2.0
|
||||
iniconfig==1.1.1
|
||||
Jinja2==2.11.3
|
||||
MarkupSafe==1.1.1
|
||||
mccabe==0.6.1
|
||||
nox==2020.12.31
|
||||
packaging==20.9
|
||||
pluggy==0.13.1
|
||||
py==1.10.0
|
||||
pycodestyle==2.7.0
|
||||
pyflakes==2.3.1
|
||||
Pygments==2.8.1
|
||||
pyparsing==2.4.7
|
||||
pytest==6.2.3
|
||||
pytz==2021.1
|
||||
requests==2.25.1
|
||||
six==1.15.0
|
||||
snowballstemmer==2.1.0
|
||||
Sphinx==3.5.4
|
||||
sphinx-rtd-theme==0.5.2
|
||||
sphinxcontrib-applehelp==1.0.2
|
||||
sphinxcontrib-devhelp==1.0.2
|
||||
sphinxcontrib-htmlhelp==1.0.3
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
sphinxcontrib-qthelp==1.0.3
|
||||
sphinxcontrib-serializinghtml==1.1.4
|
||||
toml==0.10.2
|
||||
urllib3==1.26.4
|
||||
virtualenv==20.4.3
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
cffi==1.14.0
|
||||
Pillow==6.2.2
|
||||
cffi==1.14.5
|
||||
Pillow==8.2.0
|
||||
pycparser==2.20
|
||||
pyguetzli==1.0.8
|
||||
Unidecode==1.1.1
|
||||
zopflipy==1.3
|
||||
pyguetzli==1.0.9
|
||||
Unidecode==1.2.0
|
||||
zopflipy==1.5
|
||||
|
|
|
|||
Loading…
Reference in New Issue