.. highlight:: shell
.. index:: Development
.. _Development:

===========
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


.. _venv: https://docs.python.org/3/library/venv.html

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.

.. _t3SphinxThemeRtdDemoDocs: https://docs.typo3.org/m/typo3/demo-t3SphinxThemeRtd/master/en-us/
.. _sphinx_typo3_theme: https://github.com/typo3-documentation/sphinx_typo3_theme


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:

.. code-block:: shell

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