Development

For local development you need a system with Node v12.x, Yarn, Python3, Git and make. It is strongly recommended to use a Python virtual environment (venv). The build process derives the version from repository data, so it’s necessary to clone the repository and not just download a single snapshot.

Start with make:

# show all available tasks
make

Install requirements and fulfill Python and Node demands (repeatable):

make setup

When doing frontend development compile your changes at any time:

make frontend

Build and install the package:

make install

Don’t forget to update the docs. Render the documentation and show in browser:

make docs

Without opening the browser:

non_interactive=1  make docs

Check the Python code. The CI workflow requires lint-minimal to succeed:

# for local use
make lint

# used in the workflow
make lint-minimal

Run Python unit tests:

make test

Rebuild and install from Python wheel package:

make install

# then verify the module can be imported and used
make test-import

To find out whether the created wheel package passes the twine check test and can be uploaded to PyPi run:

make build test

Grunt

More commands are available by means of grunt. Run:

grunt --help

and check the gruntfile.js.

Theme stress test

There is a demo manual t3SphinxThemeRtdDemoDocs under construction. It serves as a “stress test” for this sphinx_typo3_theme and tries to use as many reStructuredText examples as possible and covered by the theme. Documentation writers may want to have a look at those pages to understand what reST markup can be used and what the visual effect will be. Theme contributors should use the demo manual for testing and visually check the rendering.

Javascript package management

Use yarn for package management.

To upgrade a Javascript package to a newer version use the following. This keeps package.json and yarn.lock in sync as BOTH will be modified:

# ATTENTION: Select only those with reasonable version numbers.
# Be very careful if the MAJOR number would change
yarn upgrade-interactive --latest