How to use the sphinx plugin of pybuilder?

I try to create a python package using pybuilder and wonder how to make use of the sphinx plugin. I already initiated a sphinx documentation scaffold via sphinx-quickstart and activated the sphinx plugin within the build.py file of pybuilder.

The following displays my current build.py:

# import required packages
from pybuilder.core import use_plugin, init
import os
import sys
import inspect

# import required plugins
use_plugin("python.core")
use_plugin("python.unittest")
use_plugin("python.install_dependencies")
use_plugin("python.flake8")
use_plugin("python.coverage")
use_plugin("python.distutils")
use_plugin("python.sphinx")

# define build attributes
name = "presentations"
version = "0.0.1"
license = "None"
default_task = ["analyze", "publish"]


@init
def set_properties(project):
    # define unittest coverage properties
    project.set_property("coverage_threshold_warn", 50)
    project.set_property("coverage_break_build", True)
    # define linting properties
    project.set_property("flake8_break_build", False)
    project.set_property("flake8_max_line_length", 120)
    project.set_property("flake8_verbose_output", True)
    # define documentation properties
    project.set_property("sphinx_builder", "html")
    __location__ = os.path.join(os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe())))
    project.set_property("sphinx_config_path", os.path.join(__location__, '../docs'))
    project.set_property("sphinx_source_dir", os.path.join(__location__, '../src'))
    project.set_property("sphinx_output_dir", "_build/")

However, when I run the pyb command to build the package, pybuilder does not generate the desired documentation. I think, I have yet to define another default_task in addition to “analyze” and “publish” in pybuilder’s build.py file in order to force pybuilder to execute the sphinx plugin when running the pyb command.

The user awwsmm has written a super helpful tutorial on how to manage your python project with pybuilder. He also confirms that it is difficult to find a definit list of all available attributes and properties of pybuilder online. Unfortunately, the suggested search on pybuilder’s core code doesn’t help me either.

Does anyone know how to deal with that problem? Any ideas would be much appreciated.

I am coding on a windows machine using python (3.6.13), pybuilder (0.11.17) and sphinx (4.0.2).

Answer

Adding sphinx_generate_documentation to the default tasks and altering the sphinx plugin properties does the trick. The new build.py looks like:

# import required packages
from pybuilder.core import use_plugin, init
import os
import sys
import inspect

# import required plugins
use_plugin("python.core")
use_plugin("python.unittest")
use_plugin("python.install_dependencies")
use_plugin("python.flake8")
use_plugin("python.coverage")
use_plugin("python.distutils")
use_plugin("python.sphinx")

# define build attributes
name = "presentations"
version = "0.0.1"
license = "None"
default_task = ["analyze", "publish", "sphinx_generate_documentation"]


@init
def set_properties(project):
    # define unittest coverage properties
    project.set_property("coverage_threshold_warn", 50)
    project.set_property("coverage_break_build", True)
    # define linting properties
    project.set_property("flake8_break_build", False)
    project.set_property("flake8_max_line_length", 120)
    project.set_property("flake8_verbose_output", True)
    # define documentation properties
    project.set_property("sphinx_builder", "html")
    project.set_property("sphinx_config_path", "docs")
    project.set_property("sphinx_source_dir", "src/main/python")
    project.set_property("sphinx_output_dir", "docs/_build")