docs: adding command for single example build (#1893)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>
Co-authored-by: Maxime Rey <[email protected]>

Author: 4 people

doc/Makefile

@@ -37,3 +37,13 @@ html:
 # Linkcheck
 linkcheck:
 	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Single example target
+single-example:
+	@if [ -z "$(example)" ]; then \
+		echo "No example specified."; \
+		echo "Usage --> make single-example example=examples/01_getting_started/01_math.mystnb"; \
+		exit 1; \
+	fi
+	@echo "Building single example --> $(example)"
+	@BUILD_API=False SKIP_BUILD_CHEAT_SHEET=True $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" -j 1 $(O) -D "include_patterns=index.rst,examples.rst,$(example)"

doc/changelog.d/1893.documentation.md

@@ -0,0 +1 @@
+adding command for single example build

doc/make.bat

@@ -20,6 +20,7 @@ if "%1" == "clean" goto clean
 if "%1" == "pdf" goto pdf
 if "%1" == "html" goto html
 if "%1" == "linkcheck" goto linkcheck
+if "%1" == "single-example" goto single-example
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -61,6 +62,19 @@ rmdir /s /q %BUILDDIR% > /NUL 2>&1
 rmdir /s /q %APIDIR% > /NUL 2>&1
 goto end
 
+:single-example
+if "%2" == "" (
+	echo. No example specified.
+	echo. Example: ./make.bat single-example examples/01_getting_started/01_math.mystnb
+	exit /b 1
+)
+echo Building single example: %2
+set BUILD_API=false
+set SKIP_BUILD_CHEAT_SHEET=true
+set SPHINXOPTS=-j auto
+%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -D "include_patterns=index.rst,examples.rst,%2"
+goto end
+
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end

doc/source/conf.py

@@ -314,6 +314,7 @@ def intersphinx_pyansys_geometry(switcher_version: str):
     "examples/04_applied/01_naca_airfoils": "_static/thumbnails/naca_airfoils.png",
     "examples/04_applied/02_naca_fluent": "_static/thumbnails/naca_fluent.png",
     "examples/04_applied/03_ahmed_body_fluent": "_static/thumbnails/ahmed_body.png",
+    "examples/99_misc/template": "_static/thumbnails/101_getting_started.png",
 }
 nbsphinx_epilog = """
 ----
@@ -380,7 +381,9 @@ def intersphinx_pyansys_geometry(switcher_version: str):
 exclude_patterns = []
 BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
 if not BUILD_API:
-    exclude_patterns.append("autoapi")
+    exclude_patterns.append("api")
+    html_theme_options.pop("ansys_sphinx_theme_autoapi")
+    extensions.remove("ansys_sphinx_theme.extension.autoapi")
 
 BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
 if not BUILD_EXAMPLES:

doc/source/contributing.rst

@@ -138,35 +138,34 @@ To add a new example, follow these steps:
 
 1. Create a new notebook in the ``doc/source/examples`` directory, under the appropriate
    folder for your example.
-2. Take as reference an existing example to see how the notebook should be structured.
+2. Use the ``doc\source\examples\99_misc\template.mystnb`` file as a reference for creating
+   your example notebook. It contains the necessary metadata and structure for a
+   PyAnsys Geometry example.
 3. Add the new notebook to the ``doc/source/examples.rst`` file.
 4. Store a thumbnail image of the example in the ``doc/source/_static/thumbnails`` directory.
-5. Link the thumbnail image to your example file in ``doc/source/conf.py`` as shown in the reference commit.
+5. Link the thumbnail image to your example file in the ``doc/source/conf.py`` file as shown in the reference commit.
 
 You can also test the correct build process of a new example by performing the following steps:
 
 1. Run the following command to install the documentation dependencies::
 
     pip install -e .[doc]
 
-2. Install ``myst-nb`` by running this command::
+2. Navigate to the ``doc`` directory and run the following command::
 
-    pip install myst-nb
+    # On Linux or macOS
+    make single-example examples/01_getting_started/01_math.mystnb
 
-3. Run the following command to build a single example (that is, substitute
-   ``<PATH_TO_MY_EXAMPLE_FILE>`` with the path to your example file)::
+    # On Windows
+    ./make.bat single-example examples/01_getting_started/01_math.mystnb
 
-    mystnb-docutils-html --nb-read-as-md=1 <PATH_TO_MY_EXAMPLE_FILE> output.html
+  .. note::
 
-4. Check the output file ``output.html`` to ensure that the example is correctly built.
-   Rendered output does not have documentation styling but users should have the
-   ability to see its proper execution.
+    The example name must be the same as the notebook name, with its path
+    starting at the ``examples`` directory.
 
-.. note::
-
-  Plots are not be rendered in the output file, but the code and markdown cells should
-  be correctly rendered. In case of failure during execution users can also see the error
-  message in the output file.
+3. Check the ``doc/source/_build/html`` directory for the generated documentation
+   and open the ``index.html`` file in your browser.
 
 Run tests
 ---------

doc/source/examples.rst

@@ -63,4 +63,12 @@ applications.
 
     examples/04_applied/01_naca_airfoils.mystnb
     examples/04_applied/02_naca_fluent.mystnb
-    examples/04_applied/03_ahmed_body_fluent.mystnb
+    examples/04_applied/03_ahmed_body_fluent.mystnb
+
+Miscellaneous examples
+----------------------
+
+.. nbgallery::
+    :caption: Miscellaneous examples
+
+    examples/99_misc/template.mystnb

doc/source/examples/99_misc/template.mystnb

@@ -0,0 +1,91 @@
+---
+jupytext:
+  text_representation:
+    extension: .mystnb
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Miscellaneous: Example template
+
+This example serves as a template for creating new examples in the documentation.
+It shows developers how to structure their code and comments for clarity and consistency.
+It also provides a basic outline for importing necessary modules, initializing the modeler,
+performing operations, and closing the modeler.
+
+It is important to follow the conventions and formatting used in this example to ensure that
+the documentation is easy to read and understandable.
+
+## Example imports
+
+Perform the required imports for this example.
+This section should include all necessary imports for the example to run correctly.
+
+```{code-cell} ipython3
+# Imports
+from ansys.geometry.core import launch_modeler
+from ansys.geometry.core.math import Point2D
+from ansys.geometry.core.sketch import Sketch
+```
+
+## Initialize the modeler
+
+```{code-cell} ipython3
+# Initialize the modeler for this example notebook
+m = launch_modeler()
+print(m)
+```
+
+## Body of your example
+
+Developers can add their code here to perform the desired operations.
+This section should include comments and explanations to explain what the code is doing.
+
+### Example section: Initialize a design
+
+Create a design named ``example-design``.
+
+```{code-cell} ipython3
+# Initialize the example design
+design = m.create_design("example-design")
+```
+
+### Example section: Include images
+
+This section demonstrates how to include static images in the documentation.
+You should place these images in the ``doc/source/_static/`` directory.
+
+You can then reference images in the documentation using the following syntax:
+
+![image](../../_static/thumbnails/101_getting_started.png){align=center}
+
+
+### Example section: Create a sketch and plot it
+
+This section demonstrates how to create a sketch and plot it.
+
+```{code-cell} ipython3
+sketch = Sketch()
+sketch.box(Point2D([0, 0]), 10, 10)
+sketch.plot()
+```
+
+### Example section: Extrude the sketch and create a body
+This section demonstrates how to extrude the sketch and create a body.
+
+```{code-cell} ipython3
+design.extrude_sketch(f"BoxBody", sketch, distance=10)
+design.plot()
+```
+
+## Close the modeler
+
+```{code-cell} ipython3
+# Close the modeler
+m.close()
+```