Quickstart

Installation

Open a command line interface and type:

pip install sphinx-bazel

If you like, you can also use the latest, unreleased code from our repository instead:

git clone https://github.com/useblocks/sphinx-bazel
cd sphinx-bazel
pip install -e .

The above commands will install Sphinx-Bazel including all dependencies like Sphinx itself.

Project setup

After installation you can use Sphinx-Bazel inside existing Sphinx projects or create a new project via:

sphinx-quickstart

Answer the questions by your needs and sphinx-quickstart will create a new, working project for you.

Then open the conf.py file to add Sphinx-Bazel support. All you need to do is to add sphinxcontrib.sphinx_bazel to the extension list:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'sphinxcontrib.sphinx_bazel',  # <-- That's our extension
]

After this call make html to generate the html output of the fresh project. You will find the output under _build/html/.

As alternative to make you can also call sphinx-build directly:

sphinx-build -b html . _build/html

Document Bazel

Now you can start to use Sphinx-Bazel inside your project.

For instance open index.rst file and add:

.. autobazel-workspace:: <path_to_bazel_workspace>
   :packages:

Where <path_to_bazel_workspace> must be an absolute path or a relative path to the location of the conf.py file of your documentation project.

For more options and ideas how to document your Bazel project, please read Autobazel and Bazel domain.