enh: clarify Makefile and wipe out leftover from sphinxcontrib-versioning in it

Co-authored-by: Chris Markiewicz <[email protected]>

Author: oesteban

.circleci/config.yml

@@ -557,7 +557,7 @@ jobs:
           name: Build only this commit
           command: |
             BRANCH=$( echo $CIRCLE_BRANCH | sed 's+/+_+g' )
-            make -C docs SPHINXOPTS="-W" BUILDDIR="$HOME/docs" CURBRANCH=${CIRCLE_TAG:-$BRANCH} html
+            make -C docs SPHINXOPTS="-W" BUILDDIR="$HOME/docs" OUTDIR=${CIRCLE_TAG:-$BRANCH} html
       - store_artifacts:
           path: ~/docs
 

.github/workflows/docs-build-pr.yml

@@ -43,4 +43,4 @@ jobs:
 
     - name: Build docs
       run: |
-          make -C docs/ SPHINXOPTS="-W" BUILDDIR="$HOME/docs" CURBRANCH="${CURBRANCH:-html}" html
+          make -C docs/ SPHINXOPTS="-W" BUILDDIR="$HOME/docs" OUTDIR="${CURBRANCH:-html}" html

.github/workflows/docs-build-update.yml

@@ -46,7 +46,7 @@ jobs:
 
     - name: Build docs
       run: |
-          make -C docs/ SPHINXOPTS="-W" BUILDDIR="$HOME/docs" CURBRANCH="${CURBRANCH:-html}" html
+          make -C docs/ SPHINXOPTS="-W" BUILDDIR="$HOME/docs" OUTDIR="${CURBRANCH:-html}" html
 
     - name: Push created tag to gh-pages
       if: startsWith(github.ref, 'refs/tags/')

docs/Makefile

@@ -6,7 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
-CURBRANCH     = master
+OUTDIR        = html
 PYTHONPATH    = $(PWD)
 
 # User-friendly check for sphinx-build
@@ -57,9 +57,9 @@ docs-coverage:
 	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
 
 html:
-	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(CURBRANCH)
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(CURBRANCH)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(OUTDIR)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -182,6 +182,3 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-versioned:
-	PYTHONPATH=$(PYTHONPATH) sphinx-versioning -vv -l ./docs/conf.py build -r $(CURBRANCH) ./docs/ docs/$(BUILDDIR)/html/