Edit documentation build instructions

README.rst

@@ -53,8 +53,6 @@ Documentation
 
 The PyACP documentation can be viewed online at https://acp.docs.pyansys.com.
 
-.. _launching_server:
-
 Getting Started
 ---------------
 
@@ -178,9 +176,11 @@ need to create a commit without running the hooks, you can skip them with ``git
 
 Documentation
 ^^^^^^^^^^^^^
-Before generating the documentation, configure the PyACP server via the
-``ansys-launcher``, see `Launching ACP <launching_server>`_ above.
-If Ansys is installed the examples can directly built with `Sphinx`_.
+
+Basic documentation build
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build the documentation, run the following commands:
 
 On Linux & MacOS:
 
@@ -196,25 +196,62 @@ On Windows:
 
 The generated HTML files can be viewed with the browser of your choice.
 
-Alternatively you can build the documentation by starting a mapdl and pydpf-composites docker
-container. First ensure that you have accepted the DPF Preview License Agreement by setting the
-ANSYS_DPF_ACCEPT_LA environment variable to Y
-(see `DPF Preview License Agreement <https://dpf.docs.pyansys.com/version/stable/user_guide/getting_started_with_dpf_server.html#dpf-preview-license-agreement>`_
-). In addition the  ANSYSLMD_LICENSE_FILE environment variable needs be set to a
-valid license server (e.g ``[email protected]``). Then start the docker containers with:
+This method of building the documentation will run the examples with the default or currently
+configured launch options for the ACP, MAPDL, and DPF servers. Make sure to have these installed
+and configured correctly, or alternatively follow the Docker-based instructions below.
 
-.. code-block:: bash
 
-    docker compose -f docker-compose/docker-compose-extras.yaml up -d
+Alternative: start services with docker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively, you can use the provided docker-compose file to start the MAPDL and DPF servers.
 
-Then build the documentation with the `Sphinx`_ commands mentioned above.
+First, review the DPF preview license agreement, and if you agree, set the ``ANSYS_DPF_ACCEPT_LA`` environment variable to ``Y``. See `the PyDPF documentation <https://dpf.docs.pyansys.com/version/stable/getting_started/licensing.html#dpf-preview-license-agreement>`_ for details.
 
-On Windows, you can use the shipped shell script:
+On Windows, you can then use the shipped shell script:
 
 .. code-block:: batch
 
     .\doc\create_doc_windows.ps1
 
+The following manual steps can be used on any platform:
+
+1. Set the following additional environment variables in your shell:
+
+   - ``ANSYSLMD_LICENSE_FILE``: To a valid license server (e.g ``[email protected]``).
+   - ``PYMAPDL_PORT``: Choose any free port.
+   - ``PYMAPDL_START_INSTANCE=FALSE``
+   - ``PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT``: Choose any free port.
+
+2. Start the docker containers with:
+
+   .. code-block:: bash
+
+       docker compose -f docker-compose/docker-compose-extras.yaml up -d
+
+3. Build the documentation with the `Sphinx`_ commands mentioned above:
+
+   On Linux & MacOS:
+
+   .. code-block:: sh
+
+       make -C doc html
+
+   On Windows:
+
+   .. code-block:: batch
+
+       cd doc; .\make.bat html
+
+
+Partial builds
+~~~~~~~~~~~~~~
+
+Two environment variables can be used to run a quicker partial documentation build:
+
+- ``PYACP_DOC_SKIP_API=1``: Skip the API reference build.
+- ``PYACP_DOC_SKIP_GALLERY=1``: Skip running the examples.
+
 Distribution
 ^^^^^^^^^^^^
 

doc/create_doc_windows.ps1

@@ -1,30 +1,28 @@
-if ($Env:ANSYSLMD_LICENSE_FILE -ne $null)
-{
-    "ANSYSLMD_LICENSE_FILE=" + $Env:ANSYSLMD_LICENSE_FILE
-}
-else
+if ($Env:ANSYSLMD_LICENSE_FILE -eq $null)
 {
     "Env variable 'ANSYSLMD_LICENSE_FILE' is required for the license checks."
     "Example: ANSYSLMD_LICENSE_FILE='1055@my_license_server'"
     exit 1
 }
+if ($Env:ANSYS_DPF_ACCEPT_LA -ne 'Y')
+{
+    "You must review the DPF Preview license agreement, and accept it by setting the "
+    "'ANSYS_DPF_ACCEPT_LA' environment variable to 'Y' before building the PyACP documentation."
+    exit 1
+}
 
-docker pull ghcr.io/ansys/pydpf-composites:latest
-docker pull ghcr.io/ansys/mapdl:latest
-
-$Env:ANSYS_DPF_ACCEPT_LA="Y"
 $Env:PYMAPDL_PORT=59991
 $Env:PYMAPDL_START_INSTANCE="FALSE"
 $Env:PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT=59992
 $Env:SPHINXOPT_NITPICKY=0
 # whether to skip the gallery (examples)
-$Env:PYACP_DOC_SKIP_GALLERY="0"
+$Env:PYACP_DOC_SKIP_GALLERY = $Env:PYACP_DOC_SKIP_GALLERY ?? "0"
 # whether to skip the API documentation
-$Env:PYACP_DOC_SKIP_API="0"
+$Env:PYACP_DOC_SKIP_API = $Env:PYACP_DOC_SKIP_API ?? "0"
 
 $ParentDir = Split-Path -Parent $PSScriptRoot
 $DockerComposeFile = Join-Path -Path $ParentDir -ChildPath "docker-compose/docker-compose-extras.yaml"
-docker compose -f $DockerComposeFile up -d
+docker compose -f $DockerComposeFile up -d --pull always
 
 $MakeFile = Join-Path -Path $PSScriptRoot -ChildPath "make.bat"
 & $MakeFile html

docker-compose/docker-compose-extras.yaml

@@ -14,7 +14,7 @@ services:
       - ANSYS_LOCK="OFF"
   pydpf-composites-server:
     restart: unless-stopped
-    image: ${IMAGE_NAME_DPF_COMPOSITES:-ghcr.io/ansys/pydpf-composites:2023r2_pre1}
+    image: ${IMAGE_NAME_DPF_COMPOSITES:-ghcr.io/ansys/pydpf-composites:latest}
     ports:
     - "${PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT:-50558}:50052"
     environment: