diff --git a/README.rst b/README.rst index aeb488c65c..fdfdf077f7 100644 --- a/README.rst +++ b/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 `_ 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 `_ -). In addition the ANSYSLMD_LICENSE_FILE environment variable needs be set to a -valid license server (e.g ``1055@mylicenseserver.com``). 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 `_ 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 ``1055@mylicenseserver.com``). + - ``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 ^^^^^^^^^^^^ diff --git a/doc/create_doc_windows.ps1 b/doc/create_doc_windows.ps1 index 086264b279..ac0df8e27c 100644 --- a/doc/create_doc_windows.ps1 +++ b/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 diff --git a/docker-compose/docker-compose-extras.yaml b/docker-compose/docker-compose-extras.yaml index ea943f925b..3ae2023201 100644 --- a/docker-compose/docker-compose-extras.yaml +++ b/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: