======================= Developer documentation ======================= Welcome to the developer documentation of the pymetacode package. Unlike the :doc:`API documentation `, this part gives some general background information for developers who want to actively contribute to the project. Virtual environment =================== The whole development should take place inside a virtual python environment that should be located *outside* the project directory. To create a new virtual python environment, open a terminal and change to a a directory where the virtual environment should reside. Then type something like: .. code-block:: bash virtualenv pymetacode or alternatively: .. code-block:: bash python3 -m venv pymetacode This will create a virtual environment in the directory "pymetacode". To activate this virtual environment, use: .. code-block:: bash source pymetacode/bin/activate To deactivate, the command would simply be: .. code-block:: bash deactivate Autoincrementing version numbers ================================ The version number is contained in the file ``VERSION`` in the project root directory. To automatically increment the version number with every commit, use a git hook that calls the file ``bin/incrementVersion.sh``. Git hooks reside in the directory ``.git/hooks``. The simplest would be to create a new file ``pre-commit`` in this directory with the following content: .. code-block:: bash #!/bin/sh ./bin/incrementVersion.sh Make sure to set it to executable and have a line break (aka: new or empty line) at the end of the file. Otherwise, you man run into trouble, i.e., not having your version number updated automatically with each commit. Directory layout ================ The pymetacode package follows good practice of the Python community regarding directory layout. As there will be several subpackages available, these reside each in a separate directory containing its own ``__init__.py`` file. All packages/modules reside below the ``pymetacode`` directory of the project root. The ``tests`` directory follows the same structure and contains all the module tests. Generally, the pymetacode package should be developed test-driven (test-first) as much as possible. (This) documentation resides inside the ``docs`` directory of the project root. The auto-generated :doc:`API documentation ` is in its own directory. A general overview of the overall package structure: .. code-block:: bash bin/ pymetacode/ docs/ api/ tests/ Code formatting =============== Generally, code formatting follows :pep:`8` guidelines. Given that PySide does *not* follow these guidelines in several aspects, this leads to mixing different conventions. However, whenever own code is concerned, stick to the :pep:`8` guidelines. A consistent code formatting is enforced using `Black `_, with the only change to the default settings being the line width of 78 characters (as compared to the standard of 88 characters). Use ``black -l 78`` on the command line, or, preferably, configure Black in your IDE. For PyCharm (starting with 2023.2), the settings can be found in ``Preferences`` | ``Settings`` > ``Tools`` > ``Black``. Here, set ``-l 78`` as command-line options via the ``Settings`` edit field. For older PyCharm versions or other IDEs/editors see the `official Black documentation `_. To use Black, it needs to be installed. Either install it separately .. code-block:: bash pip install black or install the pymetacode package with the appropriate dependencies: .. code-block:: bash pip install pymetacode[dev] In case you are installing the pymetacode package in editable fashion (as usual for development purposes), use the following command from *within* the package directory (*i.e.*, the one containing the ``setup.py`` file): .. code-block:: pip install -e .[dev] To automatically format your Python code with every commit, use a git hook that calls the file ``bin/formatPythonFile.sh``. Git hooks reside in the directory ``.git/hooks``. The simplest would be to create a new file ``pre-commit`` with/add to the existing file in this directory the following content: .. code-block:: bash ./bin/formatPythonFile.sh For static code analysis using Prospector, see the respective :ref:`section `. Docstring format ================ The Docstring format used within the code of the pymetacode package is "NumPy". For convenience, set your IDE accordingly. For PyCharm, the settings can be found in ``Preferences`` > ``Tools`` > ``Python Integrated Tools``. Here, you find a section "Docstrings" where you can select the Docstring format from a number of different formats. Unittests and test driven development ===================================== Developing the pymetacode package code should be done test-driven wherever possible. The tests reside in the ``tests`` directory in the respective subpackage directory (see above). Tests should be written using the Python :mod:`unittest` framework. Make sure that tests are independent of the respective local environment and clean up afterwards (using appropriate ``teardown`` methods). Setting up the documentation build system ========================================= The documentation is built using `Sphinx `_, `Python `_. Building requires using a shell, for example ``bash``. To install the necessary Python dependencies, create a virtual environment, e.g., with ``virtualenv ``, and activate it afterwards with ``/bin/activate``. Then install the dependencies using ``pip``: .. code-block:: bash pip install sphinx pip install sphinx-rtd-theme pip install sphinx-multiversion Alternatively, you may simply install pymetacode with the required dependencies: .. code-block:: bash pip install pymetacode[docs] In case you are installing the pymetacode package in editable fashion (as usual for development purposes), use the following command from *within* the package directory (*i.e.*, the one containing the ``setup.py`` file): .. code-block:: pip install -e .[docs] To build the documentation: * Activate the virtual environment where the necessary dependencies are installed in. * ``cd`` to ``docs/``, then run ``make html``. (To clean previously built documentation, run ``make clean`` first). To build the documentation for all releases and the current master branch: * Activate the virtual environment where the necessary dependencies are installed in. * ``cd`` to ``docs/``, then run ``make multiversion``. (To clean previously built documentation, run ``make clean`` first). .. _sec_prospector: Static code analysis with Prospector ==================================== Static code analysis can be performed using `Prospector `_. First, install the necessary tools into the virtual environment created for the pymetacode package: .. code-block:: bash pip install prospector[with_pyroma] The optional arguments ensure that all necessary dependencies are installed as well. Alternatively, you may simply install pymetacode with the relevant dependencies: .. code-block:: bash pip install pymetacode[dev] The optional arguments ensure that all necessary dependencies are installed as well. Afterwards, simply run Prospector from a terminal from within your project root: .. code-block:: bash prospector It will display the results of the static code analysis within the terminal. Settings can be changed in the ``.prospector.yaml`` file in the project root, but please be very careful changing settings here. Often, it is better to (temporarily) silence warnings in the code itself.