CODEWITHSUNDEEP
pythonmakefilepython-sphinx
charlesreid1
charlesreid1

Reputation: 4821

How to integrate Sphinx Makefile into existing project Makefile?

I have an existing project with the following directory structure:

docs/
    conf.py
    Makefile
    index.rst
    documentation-foo.rst
    documentation-bar.rst
src/
    ...code...
common.mk
Makefile
README.rst

In the root of the repository, the Makefile contains various useful commands related to making, testing, packaging, and deploying the code. Likewise, common.mk includes a check to make sure the user has several utility programs available on their system (e.g., jq for manipulating/displaying JSON) that cannot be installed with pip. I can issue commands like make lint or make test and those are defined in that Makefile. (The top of the Makefile also has an include common.mk, see below for Makefile contents.)

In the docs/ folder, the Makefile is automatically generated by Sphinx. This Makefile is standalone and is totally independent of the Makefile or common.mk files in the root of the repository. I can issue commands like make html and it will use Sphinx to generate the documentation in HTML format.

Contents of (root) /Makefile:

include common.mk

clean:
    ...

lint:
    ...

test:
    ....

Contents of (root) /common.mk:

ifeq ($(shell which jq),)
$(error Please install jq using "apt-get install jq" or "brew install jq")
endif

Contents of (sphinx) /docs/Makefile:

# Minimal makefile for Sphinx documentation
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
...

My primary question is this: how can I incorporate the rules from the sphinx Makefile at /docs/Makefile so that they are available from the root level /Makefile?

For example, to make HTML documentation, I currently have to cd docs && make html from the root of the repo, but I would like to be able to run make html from the root of the repo and have the Makefile in the root of the repo resolve the target to the html target defined in docs/Makefile and use the rule defined in that Makefile.

Second, related question: if I have commands in docs/Makefile that have relative paths, must the paths be updated to be relative to the location where the make command is being run (the root of the repo instead of docs/), or does make resolve relative links to be relative to the Makefile's location in docs/?

Upvotes: 0

Views: 973

Answers (1)

Nick ODell
Nick ODell

Reputation: 25259

You can do this with recursive make:

html:
    $(MAKE) -C docs html

Some people strongly dislike recursive make. You can read the arguments against it, but I don't believe they apply to your use of make, since you're not trying to express dependencies.

Upvotes: 1

Related Questions