feat: add 'serve' command to Makefile and make.bat for serving documentation (#698)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Revathyvenugopal162 <[email protected]>
Co-authored-by: Revathy Venugopal <[email protected]>

Author: 3 people

doc/Makefile

@@ -4,6 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+DOCSDIR       = doc
 SOURCEDIR     = source
 BUILDDIR      = _build
 AUTOAPI_OUTDIR = source/examples/api
@@ -32,3 +33,8 @@ pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
 	(test -f $(BUILDDIR)/latex/ansys_sphinx*.pdf && echo pdf exists) || exit 1
+
+# Serve docs
+serve:
+	@echo "Serving docs..."
+	@cd ../ && stb serve $(DOCSDIR)/$(SOURCEDIR)

doc/changelog.d/698.added.md

@@ -0,0 +1 @@
+add 'serve' command to Makefile and make.bat for serving documentation

doc/make.bat

@@ -9,12 +9,14 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=source
 set BUILDDIR=_build
+set DOCSDIR=doc
 set GALLERY_EXAMPLES=%SOURCEDIR%\examples\gallery-examples
 set AUTOAPI_OUTDIR=%SOURCEDIR%\examples\api\
 
 if "%1" == "" goto help
 if "%1" == "pdf" goto pdf
 if "%1" == "clean" goto clean
+if "%1" == "serve" goto serve
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -46,5 +48,11 @@ if exist %BUILDDIR% rmdir /S /Q %BUILDDIR%
 if exist %GALLERY_EXAMPLES% rmdir /S /Q %GALLERY_EXAMPLES%
 if exist %AUTOAPI_OUTDIR% rmdir /S /Q %AUTOAPI_OUTDIR%
 
+
+:serve
+cd ../
+stb serve $(DOCSDIR)/$(SOURCEDIR)
+
+
 :end
 popd

doc/source/contribute/developer.rst

@@ -229,12 +229,55 @@ To modify the SCSS files, follow these steps:
 
 1. Navigate to the ``src/ansys_sphinx_theme/assets/styles/`` directory.
 2. Edit the relevant SCSS files as needed.
-3. Build the SCSS files using the following command:
+3. Build the library using the following command along with the documentation dependencies:
 
    .. code-block:: bash
 
       python -m pip install -e '.[doc]'
-      stb serve doc/source
+
+   This command installs the library in editable mode and builds the SCSS files.
+
+  .. important::
+
+     The built SCSS files are stored in the
+     ``src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/styles/`` directory.
+     These files are regenerated during each build process, so avoid editing them directly.
+
+4. Build the documentation and serve it locally using any of the following commands:
+
+   .. tab-set::
+
+        .. tab-item:: using Tox (recommended)
+
+            **Linux/macOS/UNIX/Windows**
+
+            .. code-block:: bash
+
+                python -m tox -e doc-serve
+
+        .. tab-item:: using Makefile
+
+            .. tab-set::
+
+                .. tab-item:: Linux or macOS
+
+                    .. code-block:: bash
+
+                        make -C doc serve
+
+                .. tab-item:: Windows
+
+                    .. code-block:: bash
+
+                        doc\make.bat serve
+
+        .. tab-item:: using stb
+
+            **Linux/macOS/UNIX/Windows**
+
+            .. code-block:: bash
+
+                stb serve doc/source
 
    After the build completes, the documentation is served on ``localhost`` and automatically opens
    in the default web browser. SCSS file changes are monitored, and the documentation rebuilds automatically.
@@ -250,11 +293,7 @@ To modify the SCSS files, follow these steps:
    This command builds the documentation, opens it in the default browser, and monitors the source files for changes to
    trigger automatic rebuilds.
 
-.. important::
 
-   The built SCSS files are stored in the
-   ``src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/styles/`` directory.
-   These files are regenerated during each build process, so avoid editing them directly.
 
 
 Build the documentation

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -1,27 +1,28 @@
 (?i)ansys
+(?i)autoapi
+(?i)Boolean
+(?i)css
+(?i)favicon
+(?i)HTML
+(?i)linkcode
+(?i)pydata
 (?i)sphinx
+(?i)Sphinx-Gallery
 (?i)theme
-(?i)Boolean
+(?i)whatsnew
+astroid
+Chris
 datatable
 debounce
-MeiliSearch
-(?i)linkcode
+Gedam
+html_context
+link_code_branch
 link_code_library
 link_code_source
-link_code_branch
-html_context
-(?i)autoapi
-(?i)HTML
+MeiliSearch
 multi-version
-(?i)css
-PDF
 namespaces
-(?i)pydata
+PDF
 Pradyun
-Gedam
-Chris
 Sewell
-(?i)Sphinx-Gallery
-(?i)favicon
-astroid
-(?i)whatsnew
+stb