From 1d05447dea3682241541e54a1466e715ad833c3a Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Tue, 14 Oct 2025 13:35:01 +0200 Subject: [PATCH] DPF Framework 26r2- transfer the changes made on 26r1 to 25r2 --- .../{changelog-25-r2.md => changelog.md} | 29 +- 2025R2/dpf-framework-25-r2/toc.yml | 2 +- .../user-guide/dpf-docs-local-preview.md | 20 +- .../user-guide/dpf-docs-local-preview.md.bak | 357 ++++++++++++++++++ 4 files changed, 374 insertions(+), 34 deletions(-) rename 2025R2/dpf-framework-25-r2/changelog/{changelog-25-r2.md => changelog.md} (94%) create mode 100644 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md.bak diff --git a/2025R2/dpf-framework-25-r2/changelog/changelog-25-r2.md b/2025R2/dpf-framework-25-r2/changelog/changelog.md similarity index 94% rename from 2025R2/dpf-framework-25-r2/changelog/changelog-25-r2.md rename to 2025R2/dpf-framework-25-r2/changelog/changelog.md index a170493ae2..e35b593b7f 100644 --- a/2025R2/dpf-framework-25-r2/changelog/changelog-25-r2.md +++ b/2025R2/dpf-framework-25-r2/changelog/changelog.md @@ -1,31 +1,11 @@ # Changelog -This changelog is organized by category, with sections for new features, changes, fixes, and performance improvements. The following table shows which components have updates in each category. - -| Component | Features | Changes | Fixes | Performance | -|-----------|----------|---------|-------|-------------| -| Framework | ✅ [15 items](#features_framework) | ✅ [4 items](#changes_framework) | ✅ [33 items](#fixes_framework) | ✅ [9 items](#performance_framework) | -| HGP | ✅ [4 items](#features_hgp) | ✅ [1 item](#changes_hgp) | ✅ [6 items](#fixes_hgp) | ✅ [2 items](#performance_hgp) | -| MAPDL | ✅ [11 items](#features_mapdl) | ✅ [3 items](#changes_mapdl) | ✅ [29 items](#fixes_mapdl) | ✅ [3 items](#performance_mapdl) | -| LSDYNA | ✅ [2 items](#features_lsdyna) | ✅ [2 items](#changes_lsdyna) | ✅ [8 items](#fixes_lsdyna) | ❌ | -| Math | ✅ [1 item](#features_math) | ✅ [2 items](#changes_math) | ✅ [1 item](#fixes_math) | ❌ | -| HDF5 | ✅ [3 items](#features_hdf5) | ✅ [1 item](#changes_hdf5) | ✅ [8 items](#fixes_hdf5) | ❌ | -| CFF | ❌ | ✅ [1 item](#changes_cff) | ✅ [2 items](#fixes_cff) | ❌ | -| Compression | ✅ [1 item](#features_compression) | ❌ | ❌ | ✅ [1 item](#performance_compression) | -| Documentation | ✅ [1 item](#features_documentation) | ❌ | ❌ | ❌ | -| Motion | ✅ [1 item](#features_motion) | ❌ | ❌ | ❌ | -| CGNS | ✅ [1 item](#features_cgns) | ❌ | ❌ | ❌ | -| Engineering Data | ❌ | ✅ [1 item](#changes_engineering_data) | ❌ | ❌ | -| VTK | ❌ | ❌ | ✅ [1 item](#fixes_vtk) | ❌ | - -**Legend:** - -- ✅ = Updates available in this category -- ❌ = No updates in this category -- Numbers in brackets indicate the count of items in each section +This changelog is organized by category, with sections for new features, changes, fixes, and performance improvements. ## Table of contents + ### Features categories + * [Framework](#features_framework) * [HGP](#features_hgp) * [MAPDL](#features_mapdl) @@ -38,6 +18,7 @@ This changelog is organized by category, with sections for new features, changes * [CGNS](#features_cgns) ### Changes categories + * [Framework](#changes_framework) * [HGP](#changes_hgp) * [MAPDL](#changes_mapdl) @@ -48,6 +29,7 @@ This changelog is organized by category, with sections for new features, changes * [Engineering Data](#changes_engineering_data) ### Fixes categories + * [Framework](#fixes_framework) * [HGP](#fixes_hgp) * [MAPDL](#fixes_mapdl) @@ -58,6 +40,7 @@ This changelog is organized by category, with sections for new features, changes * [VTK](#fixes_vtk) ### Performance improvements categories + * [Framework](#performance_framework) * [HGP](#performance_hgp) * [MAPDL](#performance_mapdl) diff --git a/2025R2/dpf-framework-25-r2/toc.yml b/2025R2/dpf-framework-25-r2/toc.yml index 73855010a1..11d0ac534a 100644 --- a/2025R2/dpf-framework-25-r2/toc.yml +++ b/2025R2/dpf-framework-25-r2/toc.yml @@ -1809,4 +1809,4 @@ - name: weighted merge fields by label href: operator-specifications/utility/weighted_merge_fields_by_label.md - name: Changelog - href: changelog/changelog-25-r2.md \ No newline at end of file + href: changelog/changelog.md \ No newline at end of file diff --git a/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md index 3ebe599267..8167be0626 100644 --- a/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md +++ b/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md @@ -18,7 +18,7 @@ This guide shows you how to create your own local copy of the DPF Framework docu This step-by-step guide walks you through: - How to use basic command-line tools. -- How to create a local website to view your custom documentation. +- How to create a local website to view your DPF Framework HTML documentation. - How to update the "Operator specifications" section of your documentation based on a custom DPF installation. ## About the command line @@ -42,7 +42,8 @@ This guide uses the **command line** (also called terminal or PowerShell on Wind Create a local website to view DPF Framework documentation in a user-friendly format (like a regular website with navigation and search). The DPF Framework documentation includes both general reference material and the DPF operators documentation. -You first get the sources for the official documentation at https://github.com/ansys/DevRelDocs, then update them locally, and generate a local website. +First, install the DocFX website builder. Next, clone the official documentation source from [github.com/ansys/DevRelDocs](https://github.com/ansys/DevRelDocs). Use DocFX to generate a local version of the website. + ### Step 1: Install the website builder (DocFX) @@ -150,7 +151,7 @@ Download and install the latest stable version of Python from the https://www.py If you want to use older versions of Python, the minimum version supported by ansys-dpf-core is 3.10. -1. **Test your Python installation** by typing: + **Test your Python installation** by typing: ```powershell python --version @@ -217,7 +218,7 @@ You need to install the DPF server software. Select the installation method that $env:ANSYS_DPF_ACCEPT_LA = "Y" ``` -1. **Set your license server** by typing: +2. **Set your license server** by typing: ```powershell $env:ANSYSLMD_LICENSE_FILE = "1055@your-license-address" @@ -225,11 +226,10 @@ You need to install the DPF server software. Select the installation method that **What these do:** Configure DPF to work with your license and permissions. See [Licensing](../getting-started/licensing.md) section for more information. -### Step 4: Update the DPF operators documentation +### Step 3: Update the DPF operators documentation Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. - **Update the current documentation with the default DPF installation:** Move to the root folder of the ``dpf-framework`` documentation downloaded in section ``Create your DPF Framework HTML documentation``, step ``Get the DPF Framework documentation source files``. @@ -278,7 +278,7 @@ Generate the output files for all operators including private operators with the dpf_generate_operators_doc.exe --include_private ``` -#### Optional: Document composites operators +#### Optional: Document Composites operators Generate the output files for all operators including operators of the ``Composites`` DPF plugin with the ``--include_composites`` command argument: @@ -289,7 +289,7 @@ dpf_generate_operators_doc.exe --include_composites This is useful for installations where the ``Composites`` plugin is present but not loaded by default. This tells the script to try and load the plugin when starting DPF. -#### Optional: Document composites operators +#### Optional: Document Sound operators Generate the output files for all operators including operators of the ``Sound`` DPF plugin with the ``--include_sound`` command argument: @@ -330,9 +330,9 @@ dpf_generate_operators_doc.exe --plugin "mesh" **What this does:** Creates documentation only for the specified plugin. -### Step 5: Rebuild the documentation +### Step 4: Rebuild the documentation -Refer to the previous main section "Create your DPF Framework HTML documentation" and "Step 3: Generate a local website" to update the HTML documentation with the new content for DPF operators. +Refer to the previous main section [Create your DPF Framework HTML documentation](#create-your-dpf-framework-html-documentation) and **Step 3: Generate a local website** to update the HTML documentation with the new content for DPF operators. ## Troubleshooting diff --git a/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md.bak b/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md.bak new file mode 100644 index 0000000000..3ebe599267 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md.bak @@ -0,0 +1,357 @@ +# Generate and preview DPF Framework documentation locally + +This guide shows you how to create your own local copy of the DPF Framework documentation that includes specifications for custom operators and development versions. + +## Before you begin + +**For most users:** If you're using a standard DPF installation, the published documentation on the [Ansys Developer Portal](https://developer.ansys.com/docs/dpf) is sufficient. + +**Use this guide if you need to:** + +- Document custom operators you've developed. +- Work with plugins that don't have published documentation. +- View documentation for development versions of DPF. +- Test changes to the DPF Framework documentation. + +## What this guide covers + +This step-by-step guide walks you through: + +- How to use basic command-line tools. +- How to create a local website to view your custom documentation. +- How to update the "Operator specifications" section of your documentation based on a custom DPF installation. + +## About the command line + +This guide uses the **command line** (also called terminal or PowerShell on Windows). + +**How to open the command line on Windows:** + +1. Press `Windows key + R` to open the Run dialog. +2. Type `powershell` and press Enter. +3. A black or blue window will open, this is your command line. + +**Important tips:** + +- Type commands exactly as shown (including spaces and punctuation). +- Press **Enter** after typing each command. +- If you see an error, double-check your typing and try again. + +## Create your DPF Framework HTML documentation + +Create a local website to view DPF Framework documentation in a user-friendly format (like a regular website with navigation and search). +The DPF Framework documentation includes both general reference material and the DPF operators documentation. + +You first get the sources for the official documentation at https://github.com/ansys/DevRelDocs, then update them locally, and generate a local website. + +### Step 1: Install the website builder (DocFX) + +DocFX is a tool that converts your documentation files into a website. + +**Open your command line** (see instructions above if you need help). + +#### Check if you have .NET installed + +First, check if your computer has the required software. + +**Type this command:** + +```powershell +dotnet --version +``` + +**What you should see:** A version number like `8.0` or higher + +**If you see an error:** You need to install .NET SDK 8.0 or later from [Microsoft's website](https://dotnet.microsoft.com/download). Download and install it, then try the command again. + +#### Install DocFX + +**Type this command:** + +```powershell +dotnet tool update -g docfx +``` + +**What this does:** Downloads and installs DocFX on your computer. + +**What you'll see:** Progress text showing the installation. + +**Verify it worked** by typing: + +```powershell +docfx --version +``` + +**What you should see:** A version number like `2.78.3` or higher. + +**If you see an error:** Try the installation command again, or ask your IT support for help. + + +### Step 2: Get the DPF Framework documentation source files + +To get the source files of the DPF Framework documentation (the basis for your custom documentation), follow these steps. + +1. **Clone the DPF Framework documentation** by typing: + + ```powershell + git clone --filter=blob:none --sparse --depth 1 https://github.com/ansys/DevRelDocs.git + cd DevRelDocs + ``` + + **What this does:** Prepares to download just the DPF Framework documentation from the repository. + +2. **Download the files** by typing: + + ```powershell + git sparse-checkout add 2025R2/dpf-framework-25-r2 + cd 2025R2/dpf-framework-25-r2 + ``` + + **What this does:** Actually downloads the documentation files of interest and puts you at the documentation root. + +### Step 3: Generate a local website + +Turn your documentation files into a viewable website. + +A default DocFX configuration file ``docfx_local.json`` is available for local documentation generation. +You can edit it to change [DocFX configuration options](https://dotnet.github.io/docfx/reference/docfx-json-reference.html) for your custom website. + +1. **Build and start your website** by typing: + + ```powershell + docfx docfx_local.json --serve + ``` + + **What this does:** + - Converts all your documentation files into a website. + - Starts a web server so you can view it. + +2. **View your documentation:** + - Open your web browser. + - Go to: . + - Use the search box to find specific operators or topics. + +3. **When you're done viewing:** + - Press `Ctrl + C` in the command line to stop the web server. + +## How to update the "Operator specifications" section + +Follow these steps to update the documentation section for DPF operators. + +It shows how to generate up-to-date Markdown source files for the DPF operators based on a given DPF installation using CPython and the ansys-dpf-core library. + +### Step 1: Install ansys-dpf-core + +This step prepares your computer with the necessary software and files. + +#### Install Python + +Download and install the latest stable version of Python from the https://www.python.org/downloads. + +If you want to use older versions of Python, the minimum version supported by ansys-dpf-core is 3.10. + +1. **Test your Python installation** by typing: + + ```powershell + python --version + ``` + + **What this does:** Shows the version of your current default Python interpreter. + +#### Create a Python virtual environment + +Python virtual environments keep your projects separate from other Python installations on your computer. +It removes the risk from incompatibilities between dependencies. + +1. **Create a new Python environment** by typing: + + ```powershell + python -m venv .my_venv + ``` + + **What this does:** Creates a folder called `.my_venv` with a clean Python environment + +2. **Activate your Python environment** by typing: + + ```powershell + .my_venv\Scripts\activate.ps1 + ``` + + **What this does:** Switches to using your new Python environment. + + **What you'll see:** Your command prompt will now show `(.my_venv)` at the beginning. + + +#### Install ansys-dpf-core + +1. **Install the latest stable version of PyDPF-Core** by typing: + + ```powershell + pip install ansys-dpf-core[operator_doc] + ``` + +This installs the ansys-dpf-core Python package with its dependencies for generating the operator documentation files. +It also enables a command on the terminal to generate the operator documentation (see the next step). + +See the [PyDPF-Core documentation](https://dpf.docs.pyansys.com/version/stable/getting_started/install.html) for further details on how you can install ansys-dpf-core. + +2. **Check your installation** with: + + ```powershell + dpf_generate_operators_doc.exe -h + ``` + + **What this does:** Checks the command for generating the operator documentation is correctly installed by ansys-dpf-core. + + **What you'll see:** Your terminal shows a description and available options for the command. + +### Step 2: Install DPF server + +You need to install the DPF server software. Select the installation method that best fits your setup. For detailed instructions, see [Installation](../getting-started/installation.md). + +#### Set up DPF permissions + +1. **Tell DPF you accept the licensing terms** by typing: + + ```powershell + $env:ANSYS_DPF_ACCEPT_LA = "Y" + ``` + +1. **Set your license server** by typing: + + ```powershell + $env:ANSYSLMD_LICENSE_FILE = "1055@your-license-address" + ``` + + **What these do:** Configure DPF to work with your license and permissions. See [Licensing](../getting-started/licensing.md) section for more information. + +### Step 4: Update the DPF operators documentation + +Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. + + +**Update the current documentation with the default DPF installation:** + +Move to the root folder of the ``dpf-framework`` documentation downloaded in section ``Create your DPF Framework HTML documentation``, step ``Get the DPF Framework documentation source files``. + +```powershell +dpf_generate_operators_doc.exe -v +``` + +**What this does:** Creates documentation files at the current location for all DPF operators of the default DPF installation picked by PyDPF-Core. + +**What you'll see:** Text showing progress as each operator is processed. This may take several minutes. + +**Wait for completion:** The command is finished when you see your command prompt again (with `(.venv)` at the beginning). + +The ``-v`` argument is used here to show progress information but can be omitted for the command to run without any output to the terminal. + +When targeting the location of the DPF Framework documentation, it updates the source files for the DPF operator specifications section. + +To learn how PyDPF-Core selects the default DPF installation, see the [PyDPF-Core documentation](https://dpf.docs.pyansys.com/version/stable/getting_started/dpf_server.html#manage-multiple-dpf-server-installations). + +#### Optional: Select the DPF installation of interest + +Update the documentation for operators of a specific DPF installation with the ``--ansys_path`` command argument: + +```powershell +dpf_generate_operators_doc.exe --ansys_path "%PATH_TO_MY_DPF_INSTALL%" +``` + +**What this does:** Creates documentation files for available DPF operators of a given DPF installation. + +#### Optional: Set the output path + +Generate the output files at a location different than the current folder with the ``--output_path`` command argument: + +```powershell +dpf_generate_operators_doc.exe --output_path "%PATH_TO_OUTPUT%" +``` + +**What this does:** Creates documentation files for available DPF operators in the default DPF installation at the given location. + +#### Optional: Document private operators + +Generate the output files for all operators including private operators with the ``--include_private`` command argument: + +```powershell +dpf_generate_operators_doc.exe --include_private +``` + +#### Optional: Document composites operators + +Generate the output files for all operators including operators of the ``Composites`` DPF plugin with the ``--include_composites`` command argument: + +```powershell +dpf_generate_operators_doc.exe --include_composites +``` + +This is useful for installations where the ``Composites`` plugin is present but not loaded by default. +This tells the script to try and load the plugin when starting DPF. + +#### Optional: Document composites operators + +Generate the output files for all operators including operators of the ``Sound`` DPF plugin with the ``--include_sound`` command argument: + +```powershell +dpf_generate_operators_doc.exe --include_sound +``` + +This is useful for installations where the ``Sound`` plugin is present but not loaded by default. +This tells the script to try and load the plugin when starting DPF. + +#### Optional: Document operators of a specific plugin + +This creates DPF operators documentation for only one plugin (faster, but incomplete). + +**Type this command:** + +```powershell +dpf_generate_operators_doc.exe --plugin "" +``` + +**Important:** Replace `` with your actual plugin name (keep the quotes). + +You can find the name of the plugin an operator belongs to on its page in the [Operator specifications](https://developer.ansys.com/docs/dpf-framework-2025-r2/operator-specifications/operator-specifications.md) section of the DPF Framework documentation under property ``plugin``. + +**Examples:** + +For the ``CFF`` plugin: + +```powershell +dpf_generate_operators_doc.exe --plugin "cff" +``` + +For the ``Mesh`` plugin: + +```powershell +dpf_generate_operators_doc.exe --plugin "mesh" +``` + +**What this does:** Creates documentation only for the specified plugin. + +### Step 5: Rebuild the documentation + +Refer to the previous main section "Create your DPF Framework HTML documentation" and "Step 3: Generate a local website" to update the HTML documentation with the new content for DPF operators. + +## Troubleshooting + +**Problem:** Command not found errors. +**Solution:** Make sure you typed the command exactly as shown, including spaces and punctuation. + +**Problem:** Permission errors. +**Solution:** Try running your command line as Administrator (right-click PowerShell and select "Run as Administrator"). + +**Problem:** Website shows errors or missing content. +**Solution:** Make sure you copied all files correctly and that your documentation generation completed successfully. + +**Problem:** Can't access the website. +**Solution:** Make sure the `docfx serve` command is still running and check that you're using . + +## Additional options + +With your working documentation website: + +- **Bookmark ** for easy access (when the server is running). +- **Re-run the generation steps** whenever you update your operators or plugins. +- **Explore customization options** in the [DocFX documentation](https://dotnet.github.io/docfx/) if you want to change the appearance.