27.10. How to test locally

In order to locally test your code, you must first fully build basf2. This will also ensure that nothing in basf2 breaks due to changes in the documentation.

To both compile basf2 and specify where the documentation output will be saved, you can use the following command:

scons --sphinx html

The output will be produced in $BELLE2_LOCAL_DIR/build/html and you can navigate it with your favorite browser to check if the output is what you expect.

If you only made changes to the analysis, framework or online_book packages, you can also add the --light option to your command to greatly speed up the compilation time.

Once basf2 has been compiled, you can build the documentation any time using

b2code-sphinx-build

If you’re only interested in sphinx warnings, use

b2code-sphinx-warnings

Tip

It is recommended to re-compile basf2 every time changes are made to the documentation to ensure that nothing in basf2 has been broken.

If you are working on a remote server with port 8XXX forwarded to your local machine (as when running a Jupyter notebook), you can also start a tiny web server on the remote machine and access it from your local machine to view the rendered documentation:

# log in to remote with port forwarding
# (8XXX is a unique number of your choice)
ssh login.cc.kek.jp -L 8XXX:localhost:8XXX
# set up basf2
cd ${BELLE2_LOCAL_DIR}/build/html
python3 -m http.server 8XXX

Now navigate to http://0.0.0.0:8XXX on your local machine to see the rendered web pages.