New Sub-packages and Modules

When adding new packages and modules (which map to folders and files) to the library you are required to update both the build/install system (setup.py) and add files to the documentation folder.

All python source code must be under the main skbeam directory. Non-python sources goes in the src directory.

Build

For a folder in the source-tree to be a package it must have an __init__.py file (even if it is empty). All of the python (*.py) files in that package are then recognized as modules in that package which can be imported in other files (See Relative Imports header).

In order for distutils to work it must be explicitly told what packages from the source tree to byte-compile and install. This is done via the packages key word argument (kwarg) to setup() in setup.py. If you add a package, then it’s dotted-name must be added to this list.

e.g. if you add a new package called utils to the skbeam folder, the following setup.py file:

setup(
    name='scikit-beam',
    version='0',
    author='Brookhaven National Lab',
    packages=["skbeam"],
    )

would need to be modified to:

setup(
    name='scikit-beam',
    version='0',
    author='Brookhaven National Lab',
    packages=["skbeam", "skbeam.utils"],   <------- modification happened here
    )

Documentation

See Documentation for documentation about writing and building the documentation.

Continuing the example from above where a ‘utils’ source code package was added, a folder called /doc/resource/api/utils should be added. Let’s also presume that you’ve got fitting.py in the /skbeam/utils/. In the documentation /doc/resource/api/utils folder, create a file named index.rst with the contents:

UTILS API
=========

Contents:

.. toctree::
   :maxdepth: 2

   fitting

Also, add the /doc/resource/api/utils/index.rst to /doc/resource/api/index.rst. This will tell sphinx to include the new package in the API documentation.

Now, let’s create a module called fitting.py in the utils package. When you add fitting.py you need to add a corresponding file in the documentation folder structure: /doc/resource/api/utils/fitting.rst. In fitting.rst use the following template:

======================
 :mod:`fitting` Module
======================

Any prose you want to add about the module, such as examples, discussion,
or saying hi to your mom can go here.

.. automodule:: skbeam.core.fitting
   :members:
   :show-inheritance:
   :undoc-members:

This will automatically walk the module to extract and format the doc strings of all the classes and functions in the module.

Testing

When you add a new module or package please add the corresponding files and folders in the skbeam/tests folder. Packages get test_packagename and modules get test_module_name.py in the proper directory.

Using the example above, you would create the directory /skbeam/tests/test_utils/ and the file test_fitting.py in the test_utils folder.

Remember: Write a test for all new functionality!!

Relative Imports

See the issue (#?) in the scikit-beam repo on github.