doc/main: add TAG make option

This splits the Sphinx tag option from SPHINXOPTS. This allows us to
specify the tag without having to remember to add -W and -t. It also
fixes not being able to specify the tag with make.bat on Windows.

While we are touching this, redundant SOURCEDIR uses are removed (main
is already the default) and the .github/workflows/publish-ide-docs.yml
script is fixed (ide directory no longer exists).

.github/workflows/build.yml

@@ -40,4 +40,4 @@ jobs:
         sudo apt-get update
         sudo apt-get install dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
     - name: Build html docs for Pybricks Code IDE
-      run: poetry run make -C doc html SOURCEDIR=main SPHINXOPTS="-W -tide"
+      run: poetry run make -C doc html TAG=ide

.github/workflows/publish-ide-docs.yml

@@ -31,8 +31,8 @@ jobs:
         node-version: '14.x'
         registry-url: 'https://registry.npmjs.org'
     - run: yarn build
-      working-directory: doc/ide
+      working-directory: doc/main
     - run: yarn publish
-      working-directory: doc/ide
+      working-directory: doc/main
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

CONTRIBUTING.md

@@ -72,6 +72,15 @@ Build docs:
     poetry run doc\make.bat html
     Invoke-Item doc\main\build\html\index.html
 
+Building IDE docs variant:
+
+    # Linux/macOS
+    poetry run make -C doc html TAG=ide
+
+    # Windows (PowerShell)
+    $env:TAG="ide"
+    poetry run doc\make.bat html
+
 Linting:
 
     poetry run flake8  # check Python

doc/Makefile

@@ -2,15 +2,16 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W -tmain
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Pybricks
 SOURCEDIR     = main
 BUILDDIR      = "$(SOURCEDIR)"/build
+TAG           = main
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)
 
 .PHONY: help Makefile
 
@@ -21,4 +22,4 @@ diagrams:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)

doc/main/conf.py

@@ -20,7 +20,8 @@ html_logo = '../common/images/pybricks-logo-rtd.png'
 latex_logo = '../common/images/pybricks-logo-large.png'
 
 # Build main docs for RTD by default.
-# Since tags cannot be passed via SPHINXOPTS on read the docs, add it manually.
+# Since tags cannot be passed via the TAG make variable on read the docs,
+# add it manually.
 if os.environ.get('READTHEDOCS', None) == 'True':
     tags.add('main')  # noqa F821
 

doc/main/package.json

@@ -18,7 +18,7 @@
   ],
   "types": "index.d.ts",
   "scripts": {
-    "clean": "poetry run make -C .. SOURCEDIR=main clean",
-    "build": "poetry run make -C .. SOURCEDIR=main SPHINXOPTS='-W -tide' html"
+    "clean": "poetry run make -C .. clean",
+    "build": "poetry run make -C .. TAG=ide html"
   }
 }

doc/make.bat

@@ -7,10 +7,13 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SPHINXOPTS=-W -tmain
+set SPHINXOPTS=-W
 set SOURCEDIR=main
 set BUILDDIR=%SOURCEDIR%/build
 set SPHINXPROJ=Pybricks
+if "%TAG%" == "" (
+	set TAG=main
+)
 
 if "%1" == "" goto help
 
@@ -27,11 +30,11 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -t %TAG%
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -t %TAG%
 
 :end
 popd