From 135aa316bd36ec65b9ebcbe6ac855472f002ed57 Mon Sep 17 00:00:00 2001 From: PProfizi Date: Fri, 10 Oct 2025 15:30:38 +0200 Subject: [PATCH 1/5] Update the introduction to the guide --- .../user-guide/dpf-docs-local-preview.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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 f7b42ce1f0..9e7c0dcaf5 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 @@ -1,6 +1,6 @@ # Generate and preview DPF Framework documentation locally -This guide shows you how to create your own local copy of DPF Framework documentation that includes specifications for custom operators and development versions. +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 @@ -11,14 +11,15 @@ This guide shows you how to create your own local copy of DPF Framework document - 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 generate DPF operators documentation files on your computer. -- How to create a local website to view your documentation. - 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 From 9c90175dfce9b972e3f2efd93e21decffa8af273 Mon Sep 17 00:00:00 2001 From: PProfizi Date: Fri, 10 Oct 2025 15:38:15 +0200 Subject: [PATCH 2/5] Rearange sections --- .../user-guide/dpf-docs-local-preview.md | 352 +++++++++--------- 1 file changed, 175 insertions(+), 177 deletions(-) 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 9e7c0dcaf5..1289c06edd 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 @@ -37,183 +37,7 @@ This guide uses the **command line** (also called terminal or PowerShell on Wind - Press **Enter** after typing each command. - If you see an error, double-check your typing and try again. -## Generate DPF operators documentation - -Follow these steps to create DPF operators documentation files. These are the Markdown source files for the DPF operators section of the documentation. - -### Step 1: Set up your working environment - -This step prepares your computer with the necessary software and files. - -#### Download the pydpf-core project - -1. **Open your command line** (see instructions above if you need help). - -2. **Navigate to a folder where you want to work**. For example, to work in your tmp folder, type: - - ```powershell - cd C:\Users\$env:USERNAME\tmp - ``` - - **What this does:** Changes your current location to your tmp folder. - -3. **Download the pydpf-core** by typing: - - ```bash - git clone https://github.com/ansys/pydpf-core.git - ``` - - **What this does:** Downloads all the pydpf-core source code to your computer. - -#### Create a Python environment - -Python environments keep your project separate from other Python installations on your computer. - -1. **Create a new Python environment** by typing: - - ```bash - python -m venv .venv - ``` - - **What this does:** Creates a folder called `.venv` with a clean Python environment - -2. **Activate your Python environment** by typing: - - ```powershell - .venv\Scripts\activate.ps1 - ``` - - **What this does:** Switches to using your new Python environment. - - **What you'll see:** Your command prompt will now show `(.venv)` at the beginning. - -#### 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 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). - -### Step 3: Install pydpf-core and required tools - -Next, install the main pydpf-core software and a tool needed for documentation generation. - -1. **Move to the pydpf-core foler** by typing: - - ```bash - cd pydpf-core - ``` - - **What this does:** Moves down one level to the `pydpf-core` folder - -2. **Install pydpf-core** by typing: - - ```bash - pip install -e . - ``` - - **What this does:** Installs pydpf-core in development mode so you can generate DPF operators documentation. - - **What you'll see:** Text showing installation progress, which may take a few minutes. - -3. **Install the documentation tool** by typing: - - ```bash - pip install jinja2 - ``` - - **What this does:** Installs Jinja2, which is needed to create the documentation files. - - **What you'll see:** Confirmation that Jinja2 was installed successfully. - -### Step 4: Generate DPF operators documentation - -Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. - -#### Option A: Generate DPF operators documentation for everything - -This creates documentation for all DPF operators (recommended for most users). - -**Type this command:** - -```bash -python .\.ci\generate_operators_doc.py -``` - -**What this does:** Creates documentation files for all available DPF operators. - -**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). - -#### Option B: Generate DPF operators documentation for one specific plugin - -This creates DPF operators documentation for only one plugin (faster, but incomplete). - -**Type this command:** - -```bash -python .\.ci\generate_operators_doc.py --plugin "" -``` - -**Important:** Replace `` with your actual plugin name (keep the quotes). - -**Examples:** - -For the CFF plugin: - -```bash -python .\.ci\generate_operators_doc.py --plugin "cff" -``` - -For the Mesh plugin: - -```bash -python .\.ci\generate_operators_doc.py --plugin "mesh" -``` - -**What this does:** Creates documentation only for the specified plugin. - -**What you'll see:** Progress text, but much faster than generating all operators. - -### Step 5: Find the DPF operators generated documentation - -DPF operators new documentation files have been created. Here's where to find them. - -**DPF operators documentation is located in:** - -```text -pydpf-core/doc/source/operators-doc/ -``` - -**What's in this folder:** - -- An `operator-specifications` folder containing multiple `.md` files (these contain your operator documentation). -- A `toc.yml` file (this creates the table of contents for your website). - -**To see these files:** - -1. Open File Explorer (Windows key + E). -2. Navigate to your pydpf-core folder. -3. Open the folders: `pydpf-core` → `source` → `operators-doc`→ `operator-specifications`. -4. You should see many `.md` files with names like operator names. - -**Next step:** Create a website to view these files in a user-friendly format. - -## Create DPF Framework HTML documentation +## 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 generated. @@ -426,6 +250,180 @@ Now you're ready to create and view your complete documentation website. 4. **When you're done viewing:** - Press `Ctrl + C` in the command line to stop the web server. +## Update the "Operator specifications" section + +Follow these steps to create DPF operators documentation files. These are the Markdown source files for the DPF operators section of the documentation. + +### Step 1: Set up your working environment + +This step prepares your computer with the necessary software and files. + +#### Download the pydpf-core project + +1. **Open your command line** (see instructions above if you need help). + +2. **Navigate to a folder where you want to work**. For example, to work in your tmp folder, type: + + ```powershell + cd C:\Users\$env:USERNAME\tmp + ``` + + **What this does:** Changes your current location to your tmp folder. + +3. **Download the pydpf-core** by typing: + + ```bash + git clone https://github.com/ansys/pydpf-core.git + ``` + + **What this does:** Downloads all the pydpf-core source code to your computer. + +#### Create a Python environment + +Python environments keep your project separate from other Python installations on your computer. + +1. **Create a new Python environment** by typing: + + ```bash + python -m venv .venv + ``` + + **What this does:** Creates a folder called `.venv` with a clean Python environment + +2. **Activate your Python environment** by typing: + + ```powershell + .venv\Scripts\activate.ps1 + ``` + + **What this does:** Switches to using your new Python environment. + + **What you'll see:** Your command prompt will now show `(.venv)` at the beginning. + +#### 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 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). + +### Step 3: Install pydpf-core and required tools + +Next, install the main pydpf-core software and a tool needed for documentation generation. + +1. **Move to the pydpf-core foler** by typing: + + ```bash + cd pydpf-core + ``` + + **What this does:** Moves down one level to the `pydpf-core` folder + +2. **Install pydpf-core** by typing: + + ```bash + pip install -e . + ``` + + **What this does:** Installs pydpf-core in development mode so you can generate DPF operators documentation. + + **What you'll see:** Text showing installation progress, which may take a few minutes. + +3. **Install the documentation tool** by typing: + + ```bash + pip install jinja2 + ``` + + **What this does:** Installs Jinja2, which is needed to create the documentation files. + + **What you'll see:** Confirmation that Jinja2 was installed successfully. + +### Step 4: Generate DPF operators documentation + +Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. + +#### Option A: Generate DPF operators documentation for everything + +This creates documentation for all DPF operators (recommended for most users). + +**Type this command:** + +```bash +python .\.ci\generate_operators_doc.py +``` + +**What this does:** Creates documentation files for all available DPF operators. + +**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). + +#### Option B: Generate DPF operators documentation for one specific plugin + +This creates DPF operators documentation for only one plugin (faster, but incomplete). + +**Type this command:** + +```bash +python .\.ci\generate_operators_doc.py --plugin "" +``` + +**Important:** Replace `` with your actual plugin name (keep the quotes). + +**Examples:** + +For the CFF plugin: + +```bash +python .\.ci\generate_operators_doc.py --plugin "cff" +``` + +For the Mesh plugin: + +```bash +python .\.ci\generate_operators_doc.py --plugin "mesh" +``` + +**What this does:** Creates documentation only for the specified plugin. + +**What you'll see:** Progress text, but much faster than generating all operators. + +### Step 5: Find the DPF operators generated documentation + +DPF operators new documentation files have been created. Here's where to find them. + +**DPF operators documentation is located in:** + +```text +pydpf-core/doc/source/operators-doc/ +``` + +**What's in this folder:** + +- An `operator-specifications` folder containing multiple `.md` files (these contain your operator documentation). +- A `toc.yml` file (this creates the table of contents for your website). + +**To see these files:** + +1. Open File Explorer (Windows key + E). +2. Navigate to your pydpf-core folder. +3. Open the folders: `pydpf-core` → `source` → `operators-doc`→ `operator-specifications`. +4. You should see many `.md` files with names like operator names. + ## Troubleshooting **Problem:** Command not found errors. From 32018941af3980ad85f73019e6f801abc83a054f Mon Sep 17 00:00:00 2001 From: PProfizi Date: Fri, 10 Oct 2025 19:05:38 +0200 Subject: [PATCH 3/5] Add a docfx_local.json --- 2025R2/dpf-framework-25-r2/docfx_local.json | 40 +++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 2025R2/dpf-framework-25-r2/docfx_local.json diff --git a/2025R2/dpf-framework-25-r2/docfx_local.json b/2025R2/dpf-framework-25-r2/docfx_local.json new file mode 100644 index 0000000000..5f9f3c0543 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/docfx_local.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json", + "build": { + "globalMetadata": { + "_appName": "DPF Framework 2025 R2", + "_appTitle": "DPF Framework 2025 R2", + "summary": "", + "version": "2025 R2", + "product": "DPF", + "programming language": "C++", + "product collection": "Structures", + "physics": "Structures", + "_enableSearch": true, + "pdf": false + }, + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "output": "_site", + "template": [ + "default", + "modern" + ] + } + } + \ No newline at end of file From a4995f3d833b006c8f0075d87feb9142e4eae865 Mon Sep 17 00:00:00 2001 From: PProfizi Date: Fri, 10 Oct 2025 19:14:43 +0200 Subject: [PATCH 4/5] Update section Create your DPF Framework HTML documentation --- .../user-guide/dpf-docs-local-preview.md | 194 ++++-------------- 1 file changed, 39 insertions(+), 155 deletions(-) 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 1289c06edd..f2016bcb66 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 @@ -39,19 +39,24 @@ This guide uses the **command line** (also called terminal or PowerShell on Wind ## 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 generated. +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:** -```bash +```powershell dotnet --version ``` @@ -63,7 +68,7 @@ dotnet --version **Type this command:** -```bash +```powershell dotnet tool update -g docfx ``` @@ -73,7 +78,7 @@ dotnet tool update -g docfx **Verify it worked** by typing: -```bash +```powershell docfx --version ``` @@ -81,176 +86,55 @@ docfx --version **If you see an error:** Try the installation command again, or ask your IT support for help. -### Step 2: Create your website project - -Create a new project that turns your documentation files into a website. - -#### Create a folder for your website - -1. **Create a new folder** for your website project. Type this command (replace `MyDPFDocs` with any name you prefer): - - ```bash - mkdir MyDPFDocs - ``` - - **What this does:** Creates a new folder called `MyDPFDocs`. - -1. **Enter your new folder** by typing: - - ```bash - cd MyDPFDocs - ``` - - **What this does:** Moves into your new folder so all the next steps happen there. - -#### Set up the website structure - -1. **Create the website structure** by typing: - - ```bash - docfx init - ``` - - **What this does:** Asks you questions to set up your website. - -2. **Answer the questions** that appear. Here's what to type for each: - - - **What's the name of your site?** Type something like `My DPF Documentation` and press **Enter**. - - **Generate .NET API documentation? (y/n)** Type `n` and press Enter. - - **Where are your docs? (docs)** Just press Enter to accept the default. - - **Enable search? (y/n)** Type `y` and press Enter (this adds a search box to your website). - - **Enable PDF? (y/n)** Type `n` and press Enter (this keeps things simple). - - **Is this OK? (y/n)** Type `y` and press Enter. - -**What you'll see:** DocFX creates several files and folders for your website. - -**Files created:** - -- `docfx.json` - Website configuration. -- `docs` folder - Where your documentation will go. -- `toc.yml` - Website navigation menu. - -#### Test your website setup - -Let's make sure everything is working before adding DPF Framework documentation. - -1. **Build and start your website** by typing: - - ```bash - docfx docfx.json --serve - ``` - - **What this does:** Creates your website and starts a local web server. - - **What you'll see:** Text ending with something like "Serving at ". - -2. **View your test website:** - - Open your web browser (Chrome, Firefox, Edge, etc.). - - Go to: `http://localhost:8080`. - - You should see a sample website with navigation. -3. **Test the documentation section:** - - Click **docs** in the top navigation. - - You should see some sample documentation pages. +### Step 2: Get the DPF Framework documentation source files -4. **Stop the website** when you're done testing: - - Go back to your command line. - - Press `Ctrl + C` to stop the web server. +To get the source files of the DPF Framework documentation (the basis for your custom documentation), follow these steps. -### Step 3: Add DPF operators documentation +1. **Clone the DPF Framework documentation** by typing: -Replace the sample content with your actual DPF operators documentation. - -#### Copy DPF operators documentation files - -**Copy the generated files:** - -1. Navigate to `pydpf-core/doc/source/operators-doc/` -2. Copy all contents to your website's `docs` folder - -### Step 4: Add complete DPF Framework documentation - -To include the complete DPF Framework documentation (beyond just the operator specifications), follow these steps. - -#### Download the complete DPF Framework documentation - -1. **Download the full DPF Framework documentation** by typing: - - ```bash - git clone --no-checkout https://github.com/ansys/DevRelDocs.git + ```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 full repository. - -2. **Set up to download only what you need** by typing: - - ```bash - git sparse-checkout init --cone - ``` - -3. **Choose which documentation to download** by typing: - - ```bash - git sparse-checkout set 2025R2/dpf-framework-25-r2 - ``` - - **What this does:** Tells Git to only download the DPF Framework documentation folder. + **What this does:** Prepares to download just the DPF Framework documentation from the repository. -4. **Download the files** by typing: +2. **Download the files** by typing: - ```bash - git checkout + ```powershell + git sparse-checkout add 2025R2/dpf-framework-25-r2 + cd 2025R2/dpf-framework-25-r2 ``` - **What this does:** Actually downloads the documentation files. - -#### Combine with your DPF operators documentation - -1. **Open File Explorer and navigate to:** - - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source). - - Your website project's `docs` folder (destination). - -2. **Copy the documentation carefully:** - - **Important:** Do NOT copy the `operator-specifications` folder from the source, as this would overwrite your custom DPF operators documentation. - - Select all other files and folders from the source (excluding `operator-specifications`). - - Copy and paste them into your website's `docs` folder. + **What this does:** Actually downloads the documentation files of interest and puts you at the documentation root. -**Result:** You now have complete DPF Framework documentation plus your custom operator specifications. +### Step 3: Generate a local website -### Step 5: Build and view your final documentation - -Now you're ready to create and view your complete documentation website. - -1. **Make sure you're in your website folder** by typing: - - ```bash - cd MyDPFDocs - ``` +Turn your documentation files into a viewable website. - (Replace `MyDPFDocs` with your actual folder name if different). +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. -2. **Build and start your documentation website** by typing: +1. **Build and start your website** by typing: - ```bash - docfx docfx.json --serve + ```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. - - Creates search functionality. -3. **View your documentation:** +2. **View your documentation:** - Open your web browser. - Go to: . - - Click **docs** to browse your documentation. - Use the search box to find specific operators or topics. -4. **When you're done viewing:** +3. **When you're done viewing:** - Press `Ctrl + C` in the command line to stop the web server. -## Update the "Operator specifications" section +## How to update the "Operator specifications" section Follow these steps to create DPF operators documentation files. These are the Markdown source files for the DPF operators section of the documentation. @@ -272,7 +156,7 @@ This step prepares your computer with the necessary software and files. 3. **Download the pydpf-core** by typing: - ```bash + ```powershell git clone https://github.com/ansys/pydpf-core.git ``` @@ -284,7 +168,7 @@ Python environments keep your project separate from other Python installations o 1. **Create a new Python environment** by typing: - ```bash + ```powershell python -m venv .venv ``` @@ -326,7 +210,7 @@ Next, install the main pydpf-core software and a tool needed for documentation g 1. **Move to the pydpf-core foler** by typing: - ```bash + ```powershell cd pydpf-core ``` @@ -334,7 +218,7 @@ Next, install the main pydpf-core software and a tool needed for documentation g 2. **Install pydpf-core** by typing: - ```bash + ```powershell pip install -e . ``` @@ -344,7 +228,7 @@ Next, install the main pydpf-core software and a tool needed for documentation g 3. **Install the documentation tool** by typing: - ```bash + ```powershell pip install jinja2 ``` @@ -362,7 +246,7 @@ This creates documentation for all DPF operators (recommended for most users). **Type this command:** -```bash +```powershell python .\.ci\generate_operators_doc.py ``` @@ -378,7 +262,7 @@ This creates DPF operators documentation for only one plugin (faster, but incomp **Type this command:** -```bash +```powershell python .\.ci\generate_operators_doc.py --plugin "" ``` @@ -388,13 +272,13 @@ python .\.ci\generate_operators_doc.py --plugin "" For the CFF plugin: -```bash +```powershell python .\.ci\generate_operators_doc.py --plugin "cff" ``` For the Mesh plugin: -```bash +```powershell python .\.ci\generate_operators_doc.py --plugin "mesh" ``` From 5cc655aff52bc83a3bf7df44cc32d8d27e86decd Mon Sep 17 00:00:00 2001 From: PProfizi Date: Mon, 13 Oct 2025 15:27:58 +0200 Subject: [PATCH 5/5] Update the usage section --- .../user-guide/dpf-docs-local-preview.md | 180 ++++++++++-------- 1 file changed, 103 insertions(+), 77 deletions(-) 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 f2016bcb66..3ebe599267 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 @@ -136,53 +136,78 @@ You can edit it to change [DocFX configuration options](https://dotnet.github.io ## How to update the "Operator specifications" section -Follow these steps to create DPF operators documentation files. These are the Markdown source files for the DPF operators section of the documentation. +Follow these steps to update the documentation section for DPF operators. -### Step 1: Set up your working environment +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. -#### Download the pydpf-core project +#### 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. -1. **Open your command line** (see instructions above if you need help). +#### Create a Python virtual environment -2. **Navigate to a folder where you want to work**. For example, to work in your tmp folder, type: +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 - cd C:\Users\$env:USERNAME\tmp + python -m venv .my_venv ``` - **What this does:** Changes your current location to your tmp folder. + **What this does:** Creates a folder called `.my_venv` with a clean Python environment -3. **Download the pydpf-core** by typing: +2. **Activate your Python environment** by typing: ```powershell - git clone https://github.com/ansys/pydpf-core.git + .my_venv\Scripts\activate.ps1 ``` - **What this does:** Downloads all the pydpf-core source code to your computer. + **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. -#### Create a Python environment -Python environments keep your project separate from other Python installations on your computer. +#### Install ansys-dpf-core -1. **Create a new Python environment** by typing: +1. **Install the latest stable version of PyDPF-Core** by typing: ```powershell - python -m venv .venv + pip install ansys-dpf-core[operator_doc] ``` - **What this does:** Creates a folder called `.venv` with a clean Python environment +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). -2. **Activate your Python environment** by typing: +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 - .venv\Scripts\activate.ps1 + dpf_generate_operators_doc.exe -h ``` - **What this does:** Switches to using your new Python environment. + **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 - **What you'll see:** Your command prompt will now show `(.venv)` at the beginning. +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 @@ -200,113 +225,114 @@ Python environments keep your project separate from other Python installations o **What these do:** Configure DPF to work with your license and permissions. See [Licensing](../getting-started/licensing.md) section for more information. -### 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). +### Step 4: Update the DPF operators documentation -### Step 3: Install pydpf-core and required tools - -Next, install the main pydpf-core software and a tool needed for documentation generation. +Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. -1. **Move to the pydpf-core foler** by typing: - ```powershell - cd pydpf-core - ``` +**Update the current documentation with the default DPF installation:** - **What this does:** Moves down one level to the `pydpf-core` folder +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``. -2. **Install pydpf-core** by typing: +```powershell +dpf_generate_operators_doc.exe -v +``` - ```powershell - pip install -e . - ``` +**What this does:** Creates documentation files at the current location for all DPF operators of the default DPF installation picked by PyDPF-Core. - **What this does:** Installs pydpf-core in development mode so you can generate DPF operators documentation. +**What you'll see:** Text showing progress as each operator is processed. This may take several minutes. - **What you'll see:** Text showing installation progress, which may take a few minutes. +**Wait for completion:** The command is finished when you see your command prompt again (with `(.venv)` at the beginning). -3. **Install the documentation tool** by typing: +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. - ```powershell - pip install jinja2 - ``` +When targeting the location of the DPF Framework documentation, it updates the source files for the DPF operator specifications section. - **What this does:** Installs Jinja2, which is needed to create the documentation files. +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). - **What you'll see:** Confirmation that Jinja2 was installed successfully. +#### Optional: Select the DPF installation of interest -### Step 4: Generate DPF operators documentation +Update the documentation for operators of a specific DPF installation with the ``--ansys_path`` command argument: -Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. +```powershell +dpf_generate_operators_doc.exe --ansys_path "%PATH_TO_MY_DPF_INSTALL%" +``` -#### Option A: Generate DPF operators documentation for everything +**What this does:** Creates documentation files for available DPF operators of a given DPF installation. -This creates documentation for all DPF operators (recommended for most users). +#### Optional: Set the output path -**Type this command:** +Generate the output files at a location different than the current folder with the ``--output_path`` command argument: ```powershell -python .\.ci\generate_operators_doc.py +dpf_generate_operators_doc.exe --output_path "%PATH_TO_OUTPUT%" ``` -**What this does:** Creates documentation files for all available DPF operators. +**What this does:** Creates documentation files for available DPF operators in the default DPF installation at the given location. -**What you'll see:** Text showing progress as each operator is processed. This may take several minutes. +#### Optional: Document private operators -**Wait for completion:** The command is finished when you see your command prompt again (with `(.venv)` at the beginning). +Generate the output files for all operators including private operators with the ``--include_private`` command argument: -#### Option B: Generate DPF operators documentation for one specific plugin +```powershell +dpf_generate_operators_doc.exe --include_private +``` -This creates DPF operators documentation for only one plugin (faster, but incomplete). +#### Optional: Document composites operators -**Type this command:** +Generate the output files for all operators including operators of the ``Composites`` DPF plugin with the ``--include_composites`` command argument: ```powershell -python .\.ci\generate_operators_doc.py --plugin "" +dpf_generate_operators_doc.exe --include_composites ``` -**Important:** Replace `` with your actual plugin name (keep the quotes). +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. -**Examples:** +#### Optional: Document composites operators -For the CFF plugin: +Generate the output files for all operators including operators of the ``Sound`` DPF plugin with the ``--include_sound`` command argument: ```powershell -python .\.ci\generate_operators_doc.py --plugin "cff" +dpf_generate_operators_doc.exe --include_sound ``` -For the Mesh plugin: +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 -python .\.ci\generate_operators_doc.py --plugin "mesh" +dpf_generate_operators_doc.exe --plugin "" ``` -**What this does:** Creates documentation only for the specified plugin. - -**What you'll see:** Progress text, but much faster than generating all operators. +**Important:** Replace `` with your actual plugin name (keep the quotes). -### Step 5: Find the DPF operators generated documentation +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``. -DPF operators new documentation files have been created. Here's where to find them. +**Examples:** -**DPF operators documentation is located in:** +For the ``CFF`` plugin: -```text -pydpf-core/doc/source/operators-doc/ +```powershell +dpf_generate_operators_doc.exe --plugin "cff" ``` -**What's in this folder:** +For the ``Mesh`` plugin: -- An `operator-specifications` folder containing multiple `.md` files (these contain your operator documentation). -- A `toc.yml` file (this creates the table of contents for your website). +```powershell +dpf_generate_operators_doc.exe --plugin "mesh" +``` + +**What this does:** Creates documentation only for the specified plugin. -**To see these files:** +### Step 5: Rebuild the documentation -1. Open File Explorer (Windows key + E). -2. Navigate to your pydpf-core folder. -3. Open the folders: `pydpf-core` → `source` → `operators-doc`→ `operator-specifications`. -4. You should see many `.md` files with names like operator names. +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