Building 3rd Party Sphinx Docs for Dash

README.md

Building 3rd Party Sphinx Docs for Dash

1. Install doc2dash.
2. Put the Makefile.dash in the projects docs/ directory.
3. Change to that directory and type make -f Makefile.dash dashdoc.

doc2dash nicely builds docs for Dash, but often the Sphinx theme is better for a web site than a dedicated documentation browser, so the make rule overrides vendor-configured HTML theme to use the epub theme, which is a better match. Ideally, this will enable building the docs without modifying the files in the vendor's repository. However, it may be necessary to edit conf.py to remove html_theme_options that are not supported by the epub theme. (It does not appear to be possible to remove unsupported options altogether with the -D option to sphinx-build. I also built the epub itself and pointed doc2dash at the generated .xhtml files but that also fails.)

Note that the doc2dash invocation automatically installs the docset -- remove the option -A is that is not desired.

Makefile.dash

# docs/Makefile.dash
include Makefile
SPHINXBUILD   = sphinx-build
BUILDDIR = $(shell pwd)
PROJECT_NAME = "mne"
.PHONY: dashdoc
dashdoc:
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) -D 'html_theme=epub' $(BUILDDIR)/dashdoc
	doc2dash -A -v -n $(PROJECT_NAME) -d $(BUILDDIR)/ -f -I index.html -j $(BUILDDIR)/dashdoc
	@echo
	@echo "Build finished. The Docset is in $(BUILDDIR)/$(PROJECT_NAME).docset."