Skip to content

Instantly share code, notes, and snippets.

@wcooley
Last active August 6, 2021 07:38
Show Gist options
  • Save wcooley/f21e36818c91eb7eff6a9e6c15587d18 to your computer and use it in GitHub Desktop.
Save wcooley/f21e36818c91eb7eff6a9e6c15587d18 to your computer and use it in GitHub Desktop.
Building 3rd Party Sphinx Docs for Dash

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.

# docs/Makefile.dash
include Makefile
PROJECT_NAME = $(shell python ../setup.py --name)
.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."
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment