Building the docs creates temporary files

MCVE

Apologies if this has already been noted, but I can’t find an open issue. When I create the docs from scratch, I see a couple temporary files and directories that appear to have been created by accident. If this is a legitimate issue, I’m happy to put together a PR.

Here is an MCVE:

(xarray-docs) gwg:doc gwg$ make clean
rm -rf _build/*
rm -rf generated/*
rm -rf auto_gallery/
(xarray-docs) gwg:doc gwg$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
(xarray-docs) gwg:doc gwg$ make html
sphinx-build -b html -d _build/doctrees   . _build/html'

...

Build finished. The HTML pages are in _build/html.
(xarray-docs) gwg:doc gwg$ git status
On branch master
Your branch is up to date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	example-no-leap.nc
	foo.zarr/
	manipulated-example-data.nc
	path/

nothing added to commit but untracked files present (use "git add" to track)

Expected Output

I would expect no files to be created by make html in the doc directory.

Problem Description

It’s not clear this will happen and may result in some people (me!) accidentally committing these files with git commit -A.

[gwgundersen]

After doing some more research, I can’t find an ipythonic way of doing this—even have a question with a bounty on StackOverflow. However, here are some options. My vote is for using the Makefile:

Remove via Makefile

It’s not ideal, but it ensures the files get removed immediately after they get created or upon clean. Near the top of the file, put something like

...
TMP_FILES = example-no-leap.nc foo.zarr/ manipulated-example-data.nc path/
...

Then the clean and html commands are

.PHONY: clean
clean:
	rm -rf $(BUILDDIR)/*
	rm -rf generated/*
	rm -rf auto_gallery/
	rm -rf $(TMP_FILES)

.PHONY: html
html:
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
	rm -rf $(TMP_FILES)
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Remove via more documentation

As @DocOtak points out, some of the documentation already cleans up after itself. Personally, I dislike this as it’s not clear to the reader why these extra snippets exist.

Remove via .gitignore

Easy to do, but I dislike this as it leaves a bunch of temporary junk in my working directory. I’d rather have it cleaned up somehow.

Remove by writing to and ignoring temp directory

Every ipython directive that creates a file should place that file in tmp/ directory. Then we .gitignore this. This is a bit cleaner than the other .gitignore option. This is my second choice.

Remove using tempdir utilities

I dislike this for the same reason I dislike “Remove via more documentation”: it clutters the documentation with utility snippets/code that are opaque to the reader.

---

Happy to create a PR for any of these, but does anyone have any preferences or a better way of doing this?

[gwgundersen]

Thanks for the explanation, @DocOtak. I didn’t initially understand :suppress:, but I now agree that a cleaning block with :suppress: is straightforward. It also follows the current pattern in the docs—I noticed this other places once I knew what to look for.