From 98aee7f3b01c28de26d47aba5182d3b631912e45 Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Thu, 4 Sep 2025 13:58:26 +0200 Subject: [PATCH 01/11] modified DPF doc generation in DPF Framework doc --- .../getting-started/dpf-docs-local-preview.md | 188 ++++++++++++++++++ .../getting-started/local-documentation.md | 100 ---------- 2 files changed, 188 insertions(+), 100 deletions(-) create mode 100644 2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md delete mode 100644 2025R2/dpf-framework-25-r2/getting-started/local-documentation.md diff --git a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md new file mode 100644 index 0000000000..157e261210 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md @@ -0,0 +1,188 @@ +# DPF documentation: Generation and local preview + +This section details how to: + +- Generate the DPF Framework documentation including operator specifications, as Markdown files using command-line tools. +- Build and serve a local HTML website to view the generated documentation using a static site generator such as Docfx. + +## Generating Documentation + +Follow the steps below to generate the DPF operator documentation in Markdown format. + +### 1. Set up the environment + +1. Clone the `pydpf-core` repository: + + ```bash + git clone + ``` + +2. Create and activate a virtual environment: + + ```bash + python -m venv .venv + .venv\Scripts\activate.ps1 + ``` + +3. Set the required environment variables: + + ```powershell + $env:ANSYS_DPF_ACCEPT_LA = "Y" + $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" + ``` + +### 2. Install the DPF server + +Navigate to the `ansys_dpf_server_win_v2025.1.pre0` folder and install the package in editable mode: + +```bash +pip install -e . +``` + +Then return to the `pydpf-core` folder: + +```bash +cd .. +``` + +### 3. Generating Documentation + +Follow these steps to generate DPF operator documentation in Markdown format. + +#### Generate documentation for all operators + +To generate documentation for **all available DPF operators**, run: + +```bash +python .\.ci\generate_operators_doc.py +``` + +#### Generate documentation for a specific plugin + +You can also generate documentation for a **specific plugin** using the `--plugin` option: + +```bash +python .\.ci\generate_operators_doc.py --plugin "" +``` + +Replace `` with the name of the plugin. + +#### Examples + +- **CFF plugin:** + + ```bash + python .\.ci\generate_operators_doc.py --plugin "cff" + ``` + +- **Mesh plugin:** + + ```bash + python .\.ci\generate_operators_doc.py --plugin "mesh" + ``` + +### 4. Locate the generated documentation + +The Markdown files and a `toc.yml` (necessary to build a local documentation website with Docfx) will be generated in: + +``` +doc/source/operators-doc +``` + +You can now copy these files into a Docfx project to preview the documentation locally. The next section explains how to install Docfx and build a local documentation website. + +Would you like me to make it **more action-oriented (step-like)** or **more formal/documentation-style**? + + +## Viewing documentation locally + +This guide explains how to install **Docfx** and use it to generate and serve a local HTML documentation site from your Markdown files. + +### Install Docfx + +#### Prerequisites + +Before installing Docfx, make sure you have the following installed: + +- [.NET SDK (6.0 or later)](https://dotnet.microsoft.com/download) + +#### Installation steps + +You can install Docfx as a global .NET tool: + +```bash +dotnet tool install -g docfx +``` + +> ✅ This makes the `docfx` command available globally from the terminal. + +To verify the installation: + +```bash +docfx --version +``` + +### Set up the documentation site + +#### Initialize a Docfx project + +Navigate to the root folder of your documentation and run: + +```bash +docfx init -q +``` + +This creates a basic Docfx project structure with a `docfx.json` configuration file. + +#### Customize the configuration + +Edit the `docfx.json` file to point to your Markdown documentation files. For example: + +```json +{ + "metadata": [], + "build": { + "content": [ + { + "files": ["**/*.md"], + "exclude": ["obj/**", "_site/**"] + } + ], + "destination": "_site" + } +} +``` + +Make sure your Markdown files are located in the correct folders relative to the configuration. + +### Copy the DPF documentation + +Replace the files in the `Articles` folder of the Docfx project with the DPF documentation generated in `doc/source/operators-doc`. + +### Build the documentation + +To generate the static HTML site: + +```bash +docfx build +``` + +The site will be generated in the `_site` directory (or the path specified in `docfx.json`). + +### Serve the documentation locally + +To view the documentation in your browser: + +```bash +docfx serve _site +``` + +Then open your browser and go to: +`http://localhost:8080` + + +**Notes** + +- You can add a custom theme or use templates to improve the design of the documentation. +- Consider placing your `docfx.json` in the root of your documentation project for easier builds. +- For more advanced configuration, see the official [Docfx documentation](https://dotnet.github.io/docfx/). diff --git a/2025R2/dpf-framework-25-r2/getting-started/local-documentation.md b/2025R2/dpf-framework-25-r2/getting-started/local-documentation.md deleted file mode 100644 index 2391bcdf27..0000000000 --- a/2025R2/dpf-framework-25-r2/getting-started/local-documentation.md +++ /dev/null @@ -1,100 +0,0 @@ -# Local documentation - -This section details how to: - -- Generate the DPF Framework documentation including operator specifications, as Markdown files using command-line tools. -- Build and serve a local HTML website to view the generated documentation using a static site generator such as DocFX. - -## Generating documentation - - - -## Viewing documentation locally - -This guide explains how to install **DocFX** and use it to generate and serve a local HTML documentation site from your Markdown files. - -### Install DocFX - -#### Prerequisites - -Before installing DocFX, make sure you have the following installed: - -- [.NET SDK (6.0 or later)](https://dotnet.microsoft.com/download) - -#### Installation steps - -You can install DocFX as a global .NET tool: - -```bash -dotnet tool install -g docfx -``` - -> ✅ This makes the `docfx` command available globally from the terminal. - -To verify the installation: - -```bash -docfx --version -``` - -### Set Up the documentation site - -#### Initialize a DocFX Project - -Navigate to the root folder of your documentation and run: - -```bash -docfx init -q -``` - -This creates a basic DocFX project structure with a `docfx.json` configuration file. - -#### Customize the Configuration - -Edit the `docfx.json` file to point to your Markdown documentation files. For example: - -```json -{ - "metadata": [], - "build": { - "content": [ - { - "files": ["**/*.md"], - "exclude": ["obj/**", "_site/**"] - } - ], - "destination": "_site" - } -} -``` - -Make sure your Markdown files are located in the correct folders relative to the configuration. - -### Build the documentation - -To generate the static HTML site: - -```bash -docfx build -``` - -The site will be generated in the `_site` directory (or the path specified in `docfx.json`). - -### Serve the documentation locally - -To view the documentation in your browser: - -```bash -docfx serve _site -``` - -Then open your browser and go to: -`http://localhost:8080` - - -**Notes** - -- You can add a custom theme or use templates to improve the design of the documentation. -- Consider placing your `docfx.json` in the root of your documentation project for easier builds. -- For more advanced configuration, see the official [DocFX documentation](https://dotnet.github.io/docfx/). - From a41fcc0e215b88b2a288af77267cf4e6a167d5a8 Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Tue, 23 Sep 2025 14:20:13 +0200 Subject: [PATCH 02/11] modified build local doc for DPF --- .../getting-started/dpf-docs-local-preview.md | 45 +++++++++++++++---- 2025R2/dpf-framework-25-r2/index.md | 8 ++-- 2025R2/dpf-framework-25-r2/toc.yml | 2 + 3 files changed, 42 insertions(+), 13 deletions(-) diff --git a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md index 157e261210..3fc4c34fb9 100644 --- a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md +++ b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md @@ -1,51 +1,78 @@ # DPF documentation: Generation and local preview +If you are using a standard DPF installation, you can access the documentation on the [Ansys Developer Portal](https://developer.ansys.com/docs/dpf). +However, if you have developed custom operators, are working with plugins that lack published documentation, or need to view documentation for a development version, you can generate comprehensive local documentation that includes detailed operator specifications for these custom components. + This section details how to: - Generate the DPF Framework documentation including operator specifications, as Markdown files using command-line tools. -- Build and serve a local HTML website to view the generated documentation using a static site generator such as Docfx. +- Build and serve a local HTML website to view the generated documentation using a static site generator such as DocFX. ## Generating Documentation Follow the steps below to generate the DPF operator documentation in Markdown format. -### 1. Set up the environment +### Set up the environment -1. Clone the `pydpf-core` repository: +1. Clone the `pydpf-core` repository. Open a terminal and run: ```bash git clone ``` -2. Create and activate a virtual environment: +2. Create and activate a virtual environment by running: ```bash python -m venv .venv .venv\Scripts\activate.ps1 ``` -3. Set the required environment variables: +3. Set the required environment variables by running: ```powershell $env:ANSYS_DPF_ACCEPT_LA = "Y" $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" ``` -### 2. Install the DPF server +### Install the DPF server + +You can install DPF in standalone or from the Ansys installer. See the [Introduction](../index.md#install-dpf) for more details. The following section details the two different ways to install DPF server. + +#### Install DPF server standalone -Navigate to the `ansys_dpf_server_win_v2025.1.pre0` folder and install the package in editable mode: +Navigate to the `ansys_dpf_server_win_v2025.1.pre0` folder (downloaded at the same level as the PyDPF Core folder) and install the package in editable mode by running: ```bash pip install -e . ``` -Then return to the `pydpf-core` folder: +#### Install DPF server from the Ansys installer + +??? + + + +### Install PyDPF core and jinja2 + +Return to the `pydpf-core` folder by running: ```bash cd .. ``` -### 3. Generating Documentation +Install the package in editable mode by running: + +```bash +pip install -e . +``` + +Install Jinja2 by running: + +```bash + pip install Jinja2 +``` + +### Generating documentation Follow these steps to generate DPF operator documentation in Markdown format. diff --git a/2025R2/dpf-framework-25-r2/index.md b/2025R2/dpf-framework-25-r2/index.md index 632aa7a63f..846a870afa 100644 --- a/2025R2/dpf-framework-25-r2/index.md +++ b/2025R2/dpf-framework-25-r2/index.md @@ -4,10 +4,10 @@ This documentation provides a comprehensive guide of the DPF framework as well a The content is organized into the following sections: -- Getting started: Learn how to install, license, and configure DPF. -- User guide: Understand the server context, work with data containers and operators, and explore workflow examples. -- Core concepts: Review essential DPF concepts and available data types. -- Operator specifications: Access detailed reference documentation for all available operators. +- Getting started: Instructions for installing, licensing, and configuring DPF. +- User guide: Learn how to work with the server context, manage data containers and operators, explore workflow examples, and build local documentation when needed. +- Core concepts: An overview of key DPF concepts and supported data types. +- Operator specifications: Detailed reference documentation for all available operators. Whether you are setting up DPF for the first time or looking for in-depth operator details, this guide provides the resources needed to use DPF effectively in your workflows. diff --git a/2025R2/dpf-framework-25-r2/toc.yml b/2025R2/dpf-framework-25-r2/toc.yml index 179a5411dc..73855010a1 100644 --- a/2025R2/dpf-framework-25-r2/toc.yml +++ b/2025R2/dpf-framework-25-r2/toc.yml @@ -18,6 +18,8 @@ href: user-guide/using-operators.md - name: Workflow examples for beginners href: user-guide/workflow-examples.md + - name: Build local documentation + href: user-guide/dpf-docs-local-preview.md - name: Core concepts items: - name: Available types From 5b7fbc0aca53513fd591bac3852f09e4137e6297 Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Wed, 24 Sep 2025 18:25:32 +0200 Subject: [PATCH 03/11] improve DPF guidelines --- .../getting-started/dpf-docs-local-preview.md | 514 ++++++++++++++---- 1 file changed, 403 insertions(+), 111 deletions(-) diff --git a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md index 3fc4c34fb9..94bfef02ef 100644 --- a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md +++ b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md @@ -1,215 +1,507 @@ -# DPF documentation: Generation and local preview +# Generate and preview DPF documentation locally -If you are using a standard DPF installation, you can access the documentation on the [Ansys Developer Portal](https://developer.ansys.com/docs/dpf). -However, if you have developed custom operators, are working with plugins that lack published documentation, or need to view documentation for a development version, you can generate comprehensive local documentation that includes detailed operator specifications for these custom components. +This guide shows you how to create your own local copy of DPF documentation that includes specifications for custom operators and development versions. -This section details how to: +## Before you begin -- Generate the DPF Framework documentation including operator specifications, as Markdown files using command-line tools. -- Build and serve a local HTML website to view the generated documentation using a static site generator such as DocFX. +**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. -## Generating Documentation +**Use this guide if you need to:** -Follow the steps below to generate the DPF operator documentation in Markdown format. +- Document custom operators you've developed +- Work with plugins that don't have published documentation +- View documentation for development versions of DPF -### Set up the environment +## What you'll learn -1. Clone the `pydpf-core` repository. Open a terminal and run: +This step-by-step guide will walk you through: + +- How to generate DPF Framework documentation files on your computer +- How to create a local website to view your documentation +- How to use basic command-line tools (don't worry - we'll explain everything!) + +## About the command line + +This guide uses the **command line** (also called terminal or PowerShell on Windows). Don't worry if you've never used it before - we'll show you exactly what to type. + +**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 + +## Generate documentation + +Follow these steps to create your DPF documentation files. + +### Step 1: Set up your working environment + +This step prepares your computer with the necessary software and files. + +#### Download the PyDPF code + +1. **Open your command line** (see instructions above if you need help) + +1. **Navigate to a folder where you want to work**. For example, to work in your Documents folder, type: + + ```powershell + cd C:\Users\$env:USERNAME\Documents + ``` + + **What this does:** Changes your current location to your Documents folder + +1. **Download the PyDPF code** by typing: ```bash git clone ``` + + **What this does:** Downloads all the PyDPF source code to your computer + + **Note:** Replace `` with the actual repository URL provided by your team + +#### Create a Python environment -2. Create and activate a virtual environment by running: +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 + +1. **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 -3. Set the required environment variables by running: +#### Set up DPF permissions + +1. **Tell DPF you accept the license** by typing: ```powershell $env:ANSYS_DPF_ACCEPT_LA = "Y" + ``` + +1. **Set your license server** by typing: + + ```powershell $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" ``` + + **What these do:** Configure DPF to work with your license and permissions -### Install the DPF server +### Step 2: Install DPF server -You can install DPF in standalone or from the Ansys installer. See the [Introduction](../index.md#install-dpf) for more details. The following section details the two different ways to install DPF server. +You need to install the DPF server software. Choose the method that matches your situation. -#### Install DPF server standalone +#### Option A: Install DPF server standalone -Navigate to the `ansys_dpf_server_win_v2025.1.pre0` folder (downloaded at the same level as the PyDPF Core folder) and install the package in editable mode by running: +Use this option if you have a standalone DPF server installation. -```bash -pip install -e . -``` +1. **Navigate to your DPF server folder**. The folder name will be something like `ansys_dpf_server_win_v2025.1.pre0`. Type: -#### Install DPF server from the Ansys installer + ```powershell + cd ansys_dpf_server_win_v2025.1.pre0 + ``` + + **What this does:** Changes to the DPF server folder + + **Note:** Make sure this folder is at the same level as your PyDPF Core folder -??? +1. **Install the DPF server** by typing: + ```bash + pip install -e . + ``` + + **What this does:** Installs the DPF server in development mode + + **What you'll see:** Text showing the installation progress +#### Option B: Install DPF server from Ansys -### Install PyDPF core and jinja2 +Use this option if you installed DPF through the standard Ansys installer. -Return to the `pydpf-core` folder by running: +If you used the Ansys installer, the DPF server is already installed and ready to use. You can skip to Step 3. -```bash -cd .. -``` +### Step 3: Install PyDPF Core and required tools -Install the package in editable mode by running: +Now you'll install the main PyDPF software and a tool needed for documentation generation. -```bash -pip install -e . -``` +1. **Go back to your PyDPF folder** by typing: -Install Jinja2 by running: + ```bash + cd .. + ``` + + **What this does:** Moves up one folder level to return to the `pydpf-core` folder -```bash - pip install Jinja2 -``` +1. **Install PyDPF Core** by typing: -### Generating documentation + ```bash + pip install -e . + ``` + + **What this does:** Installs PyDPF in development mode so you can generate documentation + + **What you'll see:** Text showing installation progress, which may take a few minutes -Follow these steps to generate DPF operator documentation in Markdown format. +1. **Install the documentation tool** by typing: -#### Generate documentation for all operators + ```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 -To generate documentation for **all available DPF operators**, run: +### Step 4: Generate your documentation + +Now you'll create the actual documentation files. Choose the option that fits your needs. + +#### Option A: Generate documentation for everything + +This creates documentation for all DPF operators (recommended for most users). + +**Type this command:** ```bash python .\.ci\generate_operators_doc.py ``` -#### Generate documentation for a specific plugin +**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. -You can also generate documentation for a **specific plugin** using the `--plugin` option: +**Wait for completion:** The command is finished when you see your command prompt again (with `(.venv)` at the beginning). + +#### Option B: Generate documentation for one specific plugin + +This creates documentation for only one plugin (faster, but incomplete). + +**Type this command:** ```bash python .\.ci\generate_operators_doc.py --plugin "" ``` -Replace `` with the name of the plugin. +**Important:** Replace `` with your actual plugin name (keep the quotes). -#### Examples +**Examples:** -- **CFF plugin:** +For the CFF plugin: - ```bash - python .\.ci\generate_operators_doc.py --plugin "cff" - ``` +```bash +python .\.ci\generate_operators_doc.py --plugin "cff" +``` -- **Mesh plugin:** +For the Mesh plugin: - ```bash - python .\.ci\generate_operators_doc.py --plugin "mesh" - ``` +```bash +python .\.ci\generate_operators_doc.py --plugin "mesh" +``` -### 4. Locate the generated documentation +**What this does:** Creates documentation only for the specified plugin -The Markdown files and a `toc.yml` (necessary to build a local documentation website with Docfx) will be generated in: +**What you'll see:** Progress text, but much faster than generating all operators -``` +### Step 5: Find your generated documentation + +Your new documentation files have been created! Here's where to find them. + +**Your documentation is located in:** + +```text doc/source/operators-doc ``` -You can now copy these files into a Docfx project to preview the documentation locally. The next section explains how to install Docfx and build a local documentation website. +**What's in this folder:** -Would you like me to make it **more action-oriented (step-like)** or **more formal/documentation-style**? +- Multiple `.md` files (these contain your documentation) +- A `toc.yml` file (this creates the table of contents for your website) +**To see these files:** -## Viewing documentation locally +1. Open File Explorer (Windows key + E) +2. Navigate to your PyDPF folder +3. Open the folders: `doc` → `source` → `operators-doc` +4. You should see many `.md` files with names like operator names -This guide explains how to install **Docfx** and use it to generate and serve a local HTML documentation site from your Markdown files. +**What's next:** You'll now create a website to view these files in a user-friendly format. -### Install Docfx +## Create your documentation website -#### Prerequisites +Now you'll create a local website to view your documentation in a user-friendly format (like a regular website with navigation and search). -Before installing Docfx, make sure you have the following installed: +### Step 1: Install the website builder (DocFX) -- [.NET SDK (6.0 or later)](https://dotnet.microsoft.com/download) +DocFX is a tool that converts your documentation files into a website. -#### Installation steps +#### Check if you have .NET installed -You can install Docfx as a global .NET tool: +First, check if your computer has the required software. + +**Type this command:** ```bash -dotnet tool install -g docfx +dotnet --version ``` -> ✅ This makes the `docfx` command available globally from the terminal. +**What you should see:** A version number like `8.0.100` 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. -To verify the installation: +#### Install DocFX + +**Type this command:** ```bash -docfx --version +dotnet tool update -g docfx ``` -### Set up the documentation site +**What this does:** Downloads and installs DocFX on your computer -#### Initialize a Docfx project +**What you'll see:** Progress text showing the installation -Navigate to the root folder of your documentation and run: +**Verify it worked** by typing: ```bash -docfx init -q +docfx --version ``` -This creates a basic Docfx project structure with a `docfx.json` configuration file. - -#### Customize the configuration - -Edit the `docfx.json` file to point to your Markdown documentation files. For example: - -```json -{ - "metadata": [], - "build": { - "content": [ - { - "files": ["**/*.md"], - "exclude": ["obj/**", "_site/**"] - } - ], - "destination": "_site" - } -} -``` +**What you should see:** A version number like `2.78.3` or higher -Make sure your Markdown files are located in the correct folders relative to the configuration. +**If you see an error:** Try the installation command again, or ask your IT support for help. -### Copy the DPF documentation -Replace the files in the `Articles` folder of the Docfx project with the DPF documentation generated in `doc/source/operators-doc`. +### Step 2: Create your website project -### Build the documentation +Now you'll create a new project that will turn your documentation files into a website. -To generate the static HTML site: +#### Create a folder for your website -```bash -docfx build -``` +1. **Create a new folder** for your website project. Type this command (replace `MyDPFDocs` with any name you prefer): -The site will be generated in the `_site` directory (or the path specified in `docfx.json`). + ```bash + mkdir MyDPFDocs + ``` + + **What this does:** Creates a new folder called `MyDPFDocs` -### Serve the documentation locally +1. **Enter your new folder** by typing: -To view the documentation in your browser: + ```bash + cd MyDPFDocs + ``` + + **What this does:** Moves into your new folder so all the next steps happen there -```bash -docfx serve _site -``` +#### 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 + +1. **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 your 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 " + +1. **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 + +1. **Test the documentation section:** + - Click **Docs** in the top navigation + - You should see some sample documentation pages + +1. **Stop the website** when you're done testing: + - Go back to your command line + - Press `Ctrl + C` to stop the web server + +### Step 3: Add your DPF documentation + +Now you'll replace the sample content with your actual DPF documentation. + +#### Copy your documentation files + +You need to copy the files you generated earlier into your website project. + +1. **Open two File Explorer windows:** + - Window 1: Go to your PyDPF folder, then `doc/source/operators-doc` + - Window 2: Go to your website folder, then open the `docs` folder + +1. **Copy all files:** + - In Window 1, select all files (Ctrl + A) + - Copy them (Ctrl + C) + - In Window 2, paste them (Ctrl + V) + - Replace any existing files when prompted + +#### Build your documentation website + +1. **Create your website with your documentation** by typing: + + ```bash + docfx docfx.json --serve + ``` + + **What you'll see:** Progress text as DocFX processes your documentation files + +1. **View your documentation website:** + - Open your web browser + - Go to: `http://localhost:8080` + - Click **Docs** to see your DPF documentation + - Use the search box to find specific operators + +### Step 4: Add complete DPF documentation (Optional) + +If you want the complete DPF documentation (not just operator specifications), follow these steps. + +**Skip this step if:** You only need the operator documentation you generated earlier. + +#### Download the complete documentation + +1. **Download the full DPF documentation** by typing: + + ```bash + git clone --no-checkout https://github.com/ansys/DevRelDocs.git + cd DevRelDocs + ``` + + **What this does:** Prepares to download just the DPF documentation from the full repository + +1. **Set up to download only what you need** by typing: + + ```bash + git sparse-checkout init --cone + ``` + +1. **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 documentation folder + +1. **Download the files** by typing: + + ```bash + git checkout + ``` + + **What this does:** Actually downloads the documentation files + +#### Combine with your generated documentation + +1. **Open File Explorer and navigate to:** + - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source) + - Your website project's `docs` folder (destination) + +1. **Copy the documentation:** + - Copy all files from the source folder + - Paste them into your website's `docs` folder + - **Important:** Don't copy files from the `operator-specifications` folder (your generated files are better) + +**Result:** You now have complete DPF documentation plus your custom operator specifications. + +### 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 + ``` + + (Replace `MyDPFDocs` with your actual folder name if different) + +1. **Build and start your documentation website** by typing: + + ```bash + docfx docfx.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 + +1. **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 + +1. **When you're done viewing:** + - Press `Ctrl + C` in the command line to stop the web server + +## 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 -Then open your browser and go to: -`http://localhost:8080` +**Problem:** Can't access the website +**Solution:** Make sure the `docfx serve` command is still running and check that you're using +## What's next -**Notes** +Now that you have a working documentation website: -- You can add a custom theme or use templates to improve the design of the documentation. -- Consider placing your `docfx.json` in the root of your documentation project for easier builds. -- For more advanced configuration, see the official [Docfx documentation](https://dotnet.github.io/docfx/). +- **Bookmark ** for easy access (when the server is running) +- **Re-run the generation steps** whenever you update your operators or plugins +- **Share the documentation files** with your team by copying the entire website folder +- **Explore customization options** in the [DocFX documentation](https://dotnet.github.io/docfx/) if you want to change the appearance From 512543d10b77aef2004fef2b1fe25eda1d31787f Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Thu, 25 Sep 2025 10:41:03 +0200 Subject: [PATCH 04/11] Finalization of improvements to the DPF guidelines --- .../getting-started/dpf-docs-local-preview.md | 225 +++++++++--------- 1 file changed, 110 insertions(+), 115 deletions(-) diff --git a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md index 94bfef02ef..0dbfae8464 100644 --- a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md +++ b/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md @@ -8,33 +8,33 @@ This guide shows you how to create your own local copy of DPF documentation that **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 +- Document custom operators you've developed. +- Work with plugins that don't have published documentation. +- View documentation for development versions of DPF. ## What you'll learn This step-by-step guide will walk you through: -- How to generate DPF Framework documentation files on your computer -- How to create a local website to view your documentation -- How to use basic command-line tools (don't worry - we'll explain everything!) +- How to generate DPF Framework documentation files on your computer. +- How to create a local website to view your documentation. +- How to use basic command-line tools. ## About the command line -This guide uses the **command line** (also called terminal or PowerShell on Windows). Don't worry if you've never used it before - we'll show you exactly what to type. +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 +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 +- 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. ## Generate documentation @@ -44,27 +44,25 @@ Follow these steps to create your DPF documentation files. This step prepares your computer with the necessary software and files. -#### Download the PyDPF code +#### Download the pydpf-core 1. **Open your command line** (see instructions above if you need help) -1. **Navigate to a folder where you want to work**. For example, to work in your Documents folder, type: +2. **Navigate to a folder where you want to work**. For example, to work in your Documents folder, type: ```powershell cd C:\Users\$env:USERNAME\Documents ``` - **What this does:** Changes your current location to your Documents folder + **What this does:** Changes your current location to your Documents folder. -1. **Download the PyDPF code** by typing: +3. **Download the pydpf-core** by typing: ```bash - git clone + git clone https://github.com/ansys/pydpf-core.git ``` - **What this does:** Downloads all the PyDPF source code to your computer - - **Note:** Replace `` with the actual repository URL provided by your team + **What this does:** Downloads all the pydpf-core source code to your computer. #### Create a Python environment @@ -78,7 +76,7 @@ Python environments keep your project separate from other Python installations o **What this does:** Creates a folder called `.venv` with a clean Python environment -1. **Activate your Python environment** by typing: +2. **Activate your Python environment** by typing: ```powershell .venv\Scripts\activate.ps1 @@ -99,10 +97,10 @@ Python environments keep your project separate from other Python installations o 1. **Set your license server** by typing: ```powershell - $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" + $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" CHANGED HERE!! ``` - **What these do:** Configure DPF to work with your license and permissions + **What these do:** Configure DPF to work with your license and permissions. ### Step 2: Install DPF server @@ -118,9 +116,9 @@ Use this option if you have a standalone DPF server installation. cd ansys_dpf_server_win_v2025.1.pre0 ``` - **What this does:** Changes to the DPF server folder + **What this does:** Changes to the DPF server folder. - **Note:** Make sure this folder is at the same level as your PyDPF Core folder + **Note:** Make sure this folder is at the same level as your pydpf-core folder. 1. **Install the DPF server** by typing: @@ -136,13 +134,13 @@ Use this option if you have a standalone DPF server installation. Use this option if you installed DPF through the standard Ansys installer. -If you used the Ansys installer, the DPF server is already installed and ready to use. You can skip to Step 3. +If you used the Ansys installer, ... ADD THE STEPS HERE!! -### Step 3: Install PyDPF Core and required tools +### Step 3: Install pydpf-core and required tools -Now you'll install the main PyDPF software and a tool needed for documentation generation. +Now you'll install the main pydpf-core software and a tool needed for documentation generation. -1. **Go back to your PyDPF folder** by typing: +1. **Go back to your pydpf-core folder** by typing: ```bash cd .. @@ -150,25 +148,25 @@ Now you'll install the main PyDPF software and a tool needed for documentation g **What this does:** Moves up one folder level to return to the `pydpf-core` folder -1. **Install PyDPF Core** by typing: +2. **Install pydpf-core** by typing: ```bash pip install -e . ``` - **What this does:** Installs PyDPF in development mode so you can generate documentation + **What this does:** Installs pydpf-core in development mode so you can generate documentation. - **What you'll see:** Text showing installation progress, which may take a few minutes + **What you'll see:** Text showing installation progress, which may take a few minutes. -1. **Install the documentation tool** by typing: +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 this does:** Installs Jinja2, which is needed to create the documentation files. - **What you'll see:** Confirmation that Jinja2 was installed successfully + **What you'll see:** Confirmation that Jinja2 was installed successfully. ### Step 4: Generate your documentation @@ -184,7 +182,7 @@ This creates documentation for all DPF operators (recommended for most users). python .\.ci\generate_operators_doc.py ``` -**What this does:** Creates documentation files for all available DPF operators +**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. @@ -216,13 +214,13 @@ For the Mesh plugin: python .\.ci\generate_operators_doc.py --plugin "mesh" ``` -**What this does:** Creates documentation only for the specified plugin +**What this does:** Creates documentation only for the specified plugin. -**What you'll see:** Progress text, but much faster than generating all operators +**What you'll see:** Progress text, but much faster than generating all operators. ### Step 5: Find your generated documentation -Your new documentation files have been created! Here's where to find them. +Your new documentation files have been created. Here's where to find them. **Your documentation is located in:** @@ -232,15 +230,15 @@ doc/source/operators-doc **What's in this folder:** -- Multiple `.md` files (these contain your documentation) -- A `toc.yml` file (this creates the table of contents for your website) +- Multiple `.md` files (these contain your 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 folder -3. Open the folders: `doc` → `source` → `operators-doc` -4. You should see many `.md` files with names like operator names +1. Open File Explorer (Windows key + E). +2. Navigate to your pydpf-core folder. +3. Open the folders: `doc` → `source` → `operators-doc`. +4. You should see many `.md` files with names like operator names. **What's next:** You'll now create a website to view these files in a user-friendly format. @@ -274,9 +272,9 @@ dotnet --version dotnet tool update -g docfx ``` -**What this does:** Downloads and installs DocFX on your computer +**What this does:** Downloads and installs DocFX on your computer. -**What you'll see:** Progress text showing the installation +**What you'll see:** Progress text showing the installation. **Verify it worked** by typing: @@ -284,7 +282,7 @@ dotnet tool update -g docfx docfx --version ``` -**What you should see:** A version number like `2.78.3` or higher +**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. @@ -301,7 +299,7 @@ Now you'll create a new project that will turn your documentation files into a w mkdir MyDPFDocs ``` - **What this does:** Creates a new folder called `MyDPFDocs` + **What this does:** Creates a new folder called `MyDPFDocs`. 1. **Enter your new folder** by typing: @@ -309,7 +307,7 @@ Now you'll create a new project that will turn your documentation files into a w cd MyDPFDocs ``` - **What this does:** Moves into your new folder so all the next steps happen there + **What this does:** Moves into your new folder so all the next steps happen there. #### Set up the website structure @@ -319,9 +317,9 @@ Now you'll create a new project that will turn your documentation files into a w docfx init ``` - **What this does:** Asks you questions to set up your website + **What this does:** Asks you questions to set up your website. -1. **Answer the questions** that appear. Here's what to type for each: +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 @@ -330,13 +328,13 @@ Now you'll create a new project that will turn your documentation files into a w - **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 +**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 +- `docfx.json` - Website configuration. +- `docs` folder - Where your documentation will go. +- `toc.yml` - Website navigation menu. #### Test your website setup @@ -348,22 +346,22 @@ Let's make sure everything is working before adding your documentation. docfx docfx.json --serve ``` - **What this does:** Creates your website and starts a local web server + **What this does:** Creates your website and starts a local web server. - **What you'll see:** Text ending with something like "Serving at " + **What you'll see:** Text ending with something like "Serving at ". -1. **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 +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. -1. **Test the documentation section:** - - Click **Docs** in the top navigation - - You should see some sample documentation pages +3. **Test the documentation section:** + - Click **docs** in the top navigation. + - You should see some sample documentation pages. -1. **Stop the website** when you're done testing: - - Go back to your command line - - Press `Ctrl + C` to stop the web server +4. **Stop the website** when you're done testing: + - Go back to your command line. + - Press `Ctrl + C` to stop the web server. ### Step 3: Add your DPF documentation @@ -374,14 +372,11 @@ Now you'll replace the sample content with your actual DPF documentation. You need to copy the files you generated earlier into your website project. 1. **Open two File Explorer windows:** - - Window 1: Go to your PyDPF folder, then `doc/source/operators-doc` + - Window 1: Go to your pydpf-core folder, then `doc/source/operators-doc` - Window 2: Go to your website folder, then open the `docs` folder -1. **Copy all files:** - - In Window 1, select all files (Ctrl + A) - - Copy them (Ctrl + C) - - In Window 2, paste them (Ctrl + V) - - Replace any existing files when prompted +2. **Copy all files:** + - In Window 1, select all files, copy them, then paste into Window 2 and replace if prompted. #### Build your documentation website @@ -391,13 +386,13 @@ You need to copy the files you generated earlier into your website project. docfx docfx.json --serve ``` - **What you'll see:** Progress text as DocFX processes your documentation files + **What you'll see:** Progress text as DocFX processes your documentation files. -1. **View your documentation website:** - - Open your web browser - - Go to: `http://localhost:8080` - - Click **Docs** to see your DPF documentation - - Use the search box to find specific operators +2. **View your documentation website:** + - Open your web browser. + - Go to: `http://localhost:8080`. + - Click **docs** in the top navigation to see your DPF documentation. + - Use the search box to find specific operators. ### Step 4: Add complete DPF documentation (Optional) @@ -414,40 +409,40 @@ If you want the complete DPF documentation (not just operator specifications), f cd DevRelDocs ``` - **What this does:** Prepares to download just the DPF documentation from the full repository + **What this does:** Prepares to download just the DPF documentation from the full repository. -1. **Set up to download only what you need** by typing: +2. **Set up to download only what you need** by typing: ```bash git sparse-checkout init --cone ``` -1. **Choose which documentation to download** by typing: +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 documentation folder + **What this does:** Tells Git to only download the DPF documentation folder. -1. **Download the files** by typing: +4. **Download the files** by typing: ```bash git checkout ``` - **What this does:** Actually downloads the documentation files + **What this does:** Actually downloads the documentation files. #### Combine with your generated documentation 1. **Open File Explorer and navigate to:** - - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source) - - Your website project's `docs` folder (destination) + - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source). + - Your website project's `docs` folder (destination). -1. **Copy the documentation:** - - Copy all files from the source folder - - Paste them into your website's `docs` folder - - **Important:** Don't copy files from the `operator-specifications` folder (your generated files are better) +2. **Copy the documentation:** + - Copy all files from the source folder. + - Paste them into your website's `docs` folder. + - **Important:** Don't copy files from the `operator-specifications` folder. **Result:** You now have complete DPF documentation plus your custom operator specifications. @@ -461,47 +456,47 @@ Now you're ready to create and view your complete documentation website. cd MyDPFDocs ``` - (Replace `MyDPFDocs` with your actual folder name if different) + (Replace `MyDPFDocs` with your actual folder name if different). -1. **Build and start your documentation website** by typing: +2. **Build and start your documentation website** by typing: ```bash docfx docfx.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 + - Converts all your documentation files into a website. + - Starts a web server so you can view it. + - Creates search functionality. -1. **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 +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. -1. **When you're done viewing:** - - Press `Ctrl + C` in the command line to stop the web server +3. **When you're done viewing:** + - Press `Ctrl + C` in the command line to stop the web server. ## Troubleshooting -**Problem:** Command not found errors -**Solution:** Make sure you typed the command exactly as shown, including spaces and punctuation +**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:** 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:** 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 +**Problem:** Can't access the website. +**Solution:** Make sure the `docfx serve` command is still running and check that you're using . ## What's next Now that you have a working documentation website: -- **Bookmark ** for easy access (when the server is running) -- **Re-run the generation steps** whenever you update your operators or plugins -- **Share the documentation files** with your team by copying the entire website folder -- **Explore customization options** in the [DocFX documentation](https://dotnet.github.io/docfx/) if you want to change the appearance +- **Bookmark ** for easy access (when the server is running). +- **Re-run the generation steps** whenever you update your operators or plugins. +- **Share the documentation files** with your team by copying the entire website folder. +- **Explore customization options** in the [DocFX documentation](https://dotnet.github.io/docfx/) if you want to change the appearance. From c4c5d42d201d889cdb7d984b39dd653a0fbd6751 Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Thu, 25 Sep 2025 10:43:12 +0200 Subject: [PATCH 05/11] Moved guidelines into user guide section in the DPF guidelines --- .../{getting-started => user-guide}/dpf-docs-local-preview.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename 2025R2/dpf-framework-25-r2/{getting-started => user-guide}/dpf-docs-local-preview.md (100%) diff --git a/2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md b/2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md similarity index 100% rename from 2025R2/dpf-framework-25-r2/getting-started/dpf-docs-local-preview.md rename to 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md From b611e492e8d4a38112bbc6c49110535b913ba107 Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Thu, 25 Sep 2025 12:05:07 +0200 Subject: [PATCH 06/11] Last improvements to the guide section in the DPF guidelines --- .../user-guide/dpf-docs-local-preview.md | 114 +++++------------- 1 file changed, 33 insertions(+), 81 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 0dbfae8464..a3d3f95f0a 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 documentation locally +# Generate and preview DPF Framework documentation locally -This guide shows you how to create your own local copy of DPF documentation that includes specifications for custom operators and development versions. +This guide shows you how to create your own local copy of DPF Framework documentation that includes specifications for custom operators and development versions. ## Before you begin @@ -26,9 +26,9 @@ This guide uses the **command line** (also called terminal or PowerShell on Wind **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 +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:** @@ -36,9 +36,9 @@ 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 documentation +## Generate DPF operators documentation -Follow these steps to create your DPF documentation files. +Follow these steps to create DPF operators documentation files. ### Step 1: Set up your working environment @@ -48,13 +48,13 @@ This step prepares your computer with the necessary software and files. 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 Documents folder, type: +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\Documents + cd C:\Users\$env:USERNAME\tmp ``` - **What this does:** Changes your current location to your Documents folder. + **What this does:** Changes your current location to your tmp folder. 3. **Download the pydpf-core** by typing: @@ -82,9 +82,9 @@ Python environments keep your project separate from other Python installations o .venv\Scripts\activate.ps1 ``` - **What this does:** Switches to using your new Python environment + **What this does:** Switches to using your new Python environment. - **What you'll see:** Your command prompt will now show `(.venv)` at the beginning + **What you'll see:** Your command prompt will now show `(.venv)` at the beginning. #### Set up DPF permissions @@ -97,44 +97,14 @@ Python environments keep your project separate from other Python installations o 1. **Set your license server** by typing: ```powershell - $env:ANSYSLMD_LICENSE_FILE = "1055@lyolmserv1.win.ansys.com" CHANGED HERE!! + $env:ANSYSLMD_LICENSE_FILE = "1055@your-license-address" ``` - **What these do:** Configure DPF to work with your license and permissions. + **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. Choose the method that matches your situation. - -#### Option A: Install DPF server standalone - -Use this option if you have a standalone DPF server installation. - -1. **Navigate to your DPF server folder**. The folder name will be something like `ansys_dpf_server_win_v2025.1.pre0`. Type: - - ```powershell - cd ansys_dpf_server_win_v2025.1.pre0 - ``` - - **What this does:** Changes to the DPF server folder. - - **Note:** Make sure this folder is at the same level as your pydpf-core folder. - -1. **Install the DPF server** by typing: - - ```bash - pip install -e . - ``` - - **What this does:** Installs the DPF server in development mode - - **What you'll see:** Text showing the installation progress - -#### Option B: Install DPF server from Ansys - -Use this option if you installed DPF through the standard Ansys installer. - -If you used the Ansys installer, ... ADD THE STEPS HERE!! +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 @@ -161,16 +131,16 @@ Now you'll install the main pydpf-core software and a tool needed for documentat 3. **Install the documentation tool** by typing: ```bash - pip install Jinja2 + 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 your documentation +### Step 4: Generate DPF operators documentation -Now you'll create the actual documentation files. Choose the option that fits your needs. +Now you'll create the actual DPF operators documentation files. Choose the option that fits your needs. #### Option A: Generate documentation for everything @@ -218,11 +188,11 @@ python .\.ci\generate_operators_doc.py --plugin "mesh" **What you'll see:** Progress text, but much faster than generating all operators. -### Step 5: Find your generated documentation +### Step 5: Find the DPF operators generated documentation -Your new documentation files have been created. Here's where to find them. +DPF operators new documentation files have been created. Here's where to find them. -**Your documentation is located in:** +**DPF operators documentation is located in:** ```text doc/source/operators-doc @@ -242,9 +212,9 @@ doc/source/operators-doc **What's next:** You'll now create a website to view these files in a user-friendly format. -## Create your documentation website +## Create DPF Framework HTML documentation -Now you'll create a local website to view your documentation in a user-friendly format (like a regular website with navigation and search). +Now you'll 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 operators documentation you generated. ### Step 1: Install the website builder (DocFX) @@ -260,7 +230,7 @@ First, check if your computer has the required software. dotnet --version ``` -**What you should see:** A version number like `8.0.100` or higher +**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. @@ -338,7 +308,7 @@ Now you'll create a new project that will turn your documentation files into a w #### Test your website setup -Let's make sure everything is working before adding your documentation. +Let's make sure everything is working before adding DPF Framework documentation. 1. **Build and start your website** by typing: @@ -363,9 +333,9 @@ Let's make sure everything is working before adding your documentation. - Go back to your command line. - Press `Ctrl + C` to stop the web server. -### Step 3: Add your DPF documentation +### Step 3: Add DPF operators documentation -Now you'll replace the sample content with your actual DPF documentation. +Now you'll replace the sample content with your actual DPF operators documentation. #### Copy your documentation files @@ -378,31 +348,13 @@ You need to copy the files you generated earlier into your website project. 2. **Copy all files:** - In Window 1, select all files, copy them, then paste into Window 2 and replace if prompted. -#### Build your documentation website - -1. **Create your website with your documentation** by typing: - - ```bash - docfx docfx.json --serve - ``` - - **What you'll see:** Progress text as DocFX processes your documentation files. - -2. **View your documentation website:** - - Open your web browser. - - Go to: `http://localhost:8080`. - - Click **docs** in the top navigation to see your DPF documentation. - - Use the search box to find specific operators. - -### Step 4: Add complete DPF documentation (Optional) - -If you want the complete DPF documentation (not just operator specifications), follow these steps. +### Step 4: Add complete DPF Framework documentation -**Skip this step if:** You only need the operator documentation you generated earlier. +To include the complete DPF Framework documentation (beyond just the operator specifications), follow these steps. -#### Download the complete documentation +#### Download the complete DPF Framework documentation -1. **Download the full DPF documentation** by typing: +1. **Download the full DPF Framework documentation** by typing: ```bash git clone --no-checkout https://github.com/ansys/DevRelDocs.git @@ -433,7 +385,7 @@ If you want the complete DPF documentation (not just operator specifications), f **What this does:** Actually downloads the documentation files. -#### Combine with your generated documentation +#### Combine with your DPF operators documentation 1. **Open File Explorer and navigate to:** - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source). @@ -444,7 +396,7 @@ If you want the complete DPF documentation (not just operator specifications), f - Paste them into your website's `docs` folder. - **Important:** Don't copy files from the `operator-specifications` folder. -**Result:** You now have complete DPF documentation plus your custom operator specifications. +**Result:** You now have complete DPF Framework documentation plus your custom operator specifications. ### Step 5: Build and view your final documentation From 47054782cfcc79ef51c1d352e5e09eb40543f64b Mon Sep 17 00:00:00 2001 From: AnsMelanie Date: Mon, 29 Sep 2025 14:52:22 +0200 Subject: [PATCH 07/11] Modified some part of the procedure in DPF Framework to clarify the local build of the doc --- .../user-guide/dpf-docs-local-preview.md | 132 +++++++++--------- 1 file changed, 63 insertions(+), 69 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 a3d3f95f0a..fb456bff35 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 @@ -9,20 +9,20 @@ This guide shows you how to create your own local copy of DPF Framework document **Use this guide if you need to:** - Document custom operators you've developed. -- Work with plugins that don't have published documentation. +- Work with plugins that don't have published documentation. - View documentation for development versions of DPF. -## What you'll learn +## What this guide covers -This step-by-step guide will walk you through: +This step-by-step guide walks you through: -- How to generate DPF Framework documentation files on your computer. +- 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. ## About the command line -This guide uses the **command line** (also called terminal or PowerShell on Windows). +This guide uses the **command line** (also called terminal or PowerShell on Windows). **How to open the command line on Windows:** @@ -46,14 +46,14 @@ This step prepares your computer with the necessary software and files. #### Download the pydpf-core -1. **Open your command line** (see instructions above if you need help) +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: @@ -61,7 +61,7 @@ This step prepares your computer with the necessary software and files. ```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 @@ -73,7 +73,7 @@ Python environments keep your project separate from other Python installations o ```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: @@ -81,9 +81,9 @@ Python environments keep your project separate from other Python installations o ```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 @@ -99,7 +99,7 @@ Python environments keep your project separate from other Python installations o ```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 @@ -108,24 +108,24 @@ You need to install the DPF server software. Select the installation method that ### Step 3: Install pydpf-core and required tools -Now you'll install the main pydpf-core software and a tool needed for documentation generation. +Next, install the main pydpf-core software and a tool needed for documentation generation. -1. **Go back to your pydpf-core folder** by typing: +1. **Move to the pydpf-core foler** by typing: ```bash - cd .. + cd pydpf-core ``` - - **What this does:** Moves up one folder level to return to the `pydpf-core` folder + + **What this does:** Moves down one folder level to return 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 documentation. - + + **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: @@ -133,16 +133,16 @@ Now you'll install the main pydpf-core software and a tool needed for documentat ```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 -Now you'll create the actual DPF operators documentation files. Choose the option that fits your needs. +Next, create the actual DPF operators documentation files. Choose the option that fits your needs. -#### Option A: Generate documentation for everything +#### Option A: Generate DPF operators documentation for everything This creates documentation for all DPF operators (recommended for most users). @@ -158,9 +158,9 @@ python .\.ci\generate_operators_doc.py **Wait for completion:** The command is finished when you see your command prompt again (with `(.venv)` at the beginning). -#### Option B: Generate documentation for one specific plugin +#### Option B: Generate DPF operators documentation for one specific plugin -This creates documentation for only one plugin (faster, but incomplete). +This creates DPF operators documentation for only one plugin (faster, but incomplete). **Type this command:** @@ -195,26 +195,26 @@ DPF operators new documentation files have been created. Here's where to find th **DPF operators documentation is located in:** ```text -doc/source/operators-doc +pydpf-core/doc/source/operators-doc/ ``` **What's in this folder:** -- Multiple `.md` files (these contain your documentation). +- 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: `doc` → `source` → `operators-doc`. +3. Open the folders: `pydpf-core` → `source` → `operators-doc`→ `operator-specifications`. 4. You should see many `.md` files with names like operator names. -**What's next:** You'll now create a website to view these files in a user-friendly format. +**Next step:** Create a website to view these files in a user-friendly format. ## Create DPF Framework HTML documentation -Now you'll 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 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 generated. ### Step 1: Install the website builder (DocFX) @@ -256,10 +256,9 @@ 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 -Now you'll create a new project that will turn your documentation files into a website. +Create a new project that turns your documentation files into a website. #### Create a folder for your website @@ -268,7 +267,7 @@ Now you'll create a new project that will turn your documentation files into a w ```bash mkdir MyDPFDocs ``` - + **What this does:** Creates a new folder called `MyDPFDocs`. 1. **Enter your new folder** by typing: @@ -276,7 +275,7 @@ Now you'll create a new project that will turn your documentation files into a w ```bash cd MyDPFDocs ``` - + **What this does:** Moves into your new folder so all the next steps happen there. #### Set up the website structure @@ -286,17 +285,17 @@ Now you'll create a new project that will turn your documentation files into a w ```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'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. @@ -315,9 +314,9 @@ Let's make sure everything is working before adding DPF Framework documentation. ```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:** @@ -335,18 +334,14 @@ Let's make sure everything is working before adding DPF Framework documentation. ### Step 3: Add DPF operators documentation -Now you'll replace the sample content with your actual DPF operators documentation. - -#### Copy your documentation files +Replace the sample content with your actual DPF operators documentation. -You need to copy the files you generated earlier into your website project. +#### Copy DPF operators documentation files -1. **Open two File Explorer windows:** - - Window 1: Go to your pydpf-core folder, then `doc/source/operators-doc` - - Window 2: Go to your website folder, then open the `docs` folder +**Copy the generated files:** -2. **Copy all files:** - - In Window 1, select all files, copy them, then paste into Window 2 and replace if prompted. +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 @@ -360,8 +355,8 @@ To include the complete DPF Framework documentation (beyond just the operator sp git clone --no-checkout https://github.com/ansys/DevRelDocs.git cd DevRelDocs ``` - - **What this does:** Prepares to download just the DPF documentation from the full repository. + + **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: @@ -374,15 +369,15 @@ To include the complete DPF Framework documentation (beyond just the operator sp ```bash git sparse-checkout set 2025R2/dpf-framework-25-r2 ``` - - **What this does:** Tells Git to only download the DPF documentation folder. + + **What this does:** Tells Git to only download the DPF Framework documentation folder. 4. **Download the files** by typing: ```bash git checkout ``` - + **What this does:** Actually downloads the documentation files. #### Combine with your DPF operators documentation @@ -391,10 +386,10 @@ To include the complete DPF Framework documentation (beyond just the operator sp - Your `DevRelDocs/2025R2/dpf-framework-25-r2` folder (source). - Your website project's `docs` folder (destination). -2. **Copy the documentation:** - - Copy all files from the source folder. - - Paste them into your website's `docs` folder. - - **Important:** Don't copy files from the `operator-specifications` folder. +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. **Result:** You now have complete DPF Framework documentation plus your custom operator specifications. @@ -407,7 +402,7 @@ Now you're ready to create and view your complete documentation website. ```bash cd MyDPFDocs ``` - + (Replace `MyDPFDocs` with your actual folder name if different). 2. **Build and start your documentation website** by typing: @@ -415,19 +410,19 @@ Now you're ready to create and view your complete documentation website. ```bash docfx docfx.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. -2. **View your documentation:** +3. **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. -3. **When you're done viewing:** +4. **When you're done viewing:** - Press `Ctrl + C` in the command line to stop the web server. ## Troubleshooting @@ -444,11 +439,10 @@ Now you're ready to create and view your complete documentation website. **Problem:** Can't access the website. **Solution:** Make sure the `docfx serve` command is still running and check that you're using . -## What's next +## Additional options -Now that you have a working documentation website: +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. -- **Share the documentation files** with your team by copying the entire website folder. - **Explore customization options** in the [DocFX documentation](https://dotnet.github.io/docfx/) if you want to change the appearance. From 17482bc8d3a4af5c4ad98de34a849e63f8bc6a54 Mon Sep 17 00:00:00 2001 From: AnsMelanie <138772358+AnsMelanie@users.noreply.github.com> Date: Tue, 30 Sep 2025 14:53:51 +0200 Subject: [PATCH 08/11] Update 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fb456bff35..6aad320175 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 @@ -88,7 +88,7 @@ Python environments keep your project separate from other Python installations o #### Set up DPF permissions -1. **Tell DPF you accept the license** by typing: +1. **Tell DPF you accept the licensing terms** by typing: ```powershell $env:ANSYS_DPF_ACCEPT_LA = "Y" From d1fc41d9a73e463e0bdbab5979bdfc6a633b0dec Mon Sep 17 00:00:00 2001 From: AnsMelanie <138772358+AnsMelanie@users.noreply.github.com> Date: Tue, 30 Sep 2025 14:54:37 +0200 Subject: [PATCH 09/11] Update 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 6aad320175..22164294ac 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 @@ -116,7 +116,7 @@ Next, install the main pydpf-core software and a tool needed for documentation g cd pydpf-core ``` - **What this does:** Moves down one folder level to return to the `pydpf-core` folder + **What this does:** Moves down one level to the `pydpf-core` folder 2. **Install pydpf-core** by typing: From fbb4b9d464e7a8bd9a187408328ec27a2321eba3 Mon Sep 17 00:00:00 2001 From: AnsMelanie <138772358+AnsMelanie@users.noreply.github.com> Date: Tue, 30 Sep 2025 15:52:29 +0200 Subject: [PATCH 10/11] Update 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 22164294ac..a38d00e23b 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 @@ -44,7 +44,7 @@ Follow these steps to create DPF operators documentation files. This step prepares your computer with the necessary software and files. -#### Download the pydpf-core +#### Download the pydpf-core project 1. **Open your command line** (see instructions above if you need help). From 0f6260d3fccf41daedb9a30fcf0a207c529f7af0 Mon Sep 17 00:00:00 2001 From: AnsMelanie <138772358+AnsMelanie@users.noreply.github.com> Date: Wed, 1 Oct 2025 11:04:47 +0200 Subject: [PATCH 11/11] Update 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- 2025R2/dpf-framework-25-r2/user-guide/dpf-docs-local-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 a38d00e23b..cc64248ce7 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 @@ -140,7 +140,7 @@ Next, install the main pydpf-core software and a tool needed for documentation g ### Step 4: Generate DPF operators documentation -Next, create the actual DPF operators documentation files. Choose the option that fits your needs. +Next, generate the DPF operators Markdown documentation files. Choose the option that fits your needs. #### Option A: Generate DPF operators documentation for everything