Contributing and Developer’s Guide#

Contributing#

Any contributions are welcomed.

Run on Actual GPUs#

One of the most lacking part is running on various GPUs. Any feedbacks are appriciated.

When Find any problems / bugs#

Check issues first, and open new one unless the same problem has been reported.

Developer’s Guide#

Code Layout#

  • vulkpy/ (Main Package)

    • vkarray.py

      • Python core implementation

    • _vkarray.cc, _vkarray.hh

      • C++ internal implementation

    • shader/

      • GPU shaders

    • nn/

      • Neural Network implementation

    • random.py

      • Pseudo Random Number Generator (PRNG) implementation

    • util.py

      • Utility Function implementation

    • vktyping.py

      • Type implementation

  • doc/

    • Document Site

  • example/

    • Example Codes

  • test/

    • Test Codes

  • .github/

    • CI configuration

  • README.md, LICENSE

    • Project-wide information.

  • setup.py, pyproject.toml, MANIFEST.in

    • Configuration for Package Build

  • .coverage

    • Configuration for Coverage

  • Dockerfile, .dockerignore

    • Configuration for CI tasks (See below)

  • mypy.ini

    • Configuration for Type Check

  • .gitignore

Continuous Integration (CI) & Continuous Delivery (CD)#

We use GitHub Actions for CI/CD, and its configuration is defined at .github/workflows/vulkpy.yaml

To make CI independent from the platform as much as possible, we define actual CI tasks inside Dockerfile.

Document Site#

Document site is generated by Sphinx during CI/CD. We adopt furo theme.

Most documents are written in markdown (.md) and parsed by MyST.

All markdown files are located at doc/ directory flatly. Even if we restructure document site in future, flatten layout can prevent broken link.

API reference is automatically generated from docstring with sphinx-automodapi.

docstring#

To make the usage understandable, all public classes and methods should have docstring.

Shpinx generates API reference from these docstring.

Basically we obey Numpy’s style guide, however, we adopt following PEP-257 statement for class docstring;

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its init method. Individual methods should be documented by their own docstring.

To separate class docstring and __init__() docstring, we configure Sphinx as follows;

autodoc_class_signature = "separated"
autodoc_default_options = {
    "class-doc-from": "class"
}