refactor: formatting webserver scripts

[germa89]

Description

As the title.

Although they are not used much.

Issue linked

NA

Checklist

• I have visited and read Develop PyMAPDL.
• I have tested my changes locally
• I have added necessary documentation or updated existing documentation.
• I have followed the PyMAPDL coding style guidelines.
• I have added appropriate unit tests that also ensure the minimal coverage criteria.
• I have reviewed my changes before submitting this pull request.
• I have linked the issue or issues that are solved to the PR if any.
• I have assigned this PR to myself.
• I have marked this PR as draft if it is not ready to be reviewed yet.
• I have made sure that the title of my PR follows Commit naming conventions (e.g. feat: adding new MAPDL command)

Summary by Sourcery

Standardize formatting, shebang usage, and environment handling across CI, devcontainer, and documentation shell scripts; add a dedicated webserver script for serving HTML docs; and integrate ShellCheck into pre-commit.

New Features:

• Add doc/webserver.sh to start and stop a Python HTTP server for serving HTML documentation.

Enhancements:

• Standardize shebangs, headers, and environment variable exports in CI and devcontainer shell scripts.
• Harmonize file path patterns and mv commands in log collection and display scripts with explicit './' prefixes.
• Introduce AUTH_USER flag with default value and uppercase usage in build_matrix.sh.
• Enforce exit-on-failure for cd operations and add shellcheck disable directives in devcontainer startup scripts.

CI:

• Add ShellCheck hook to pre-commit configuration.

Documentation:

• Add changelog entry for ShellCheck pre-commit hook.

Chores:

• Remove legacy start_webserver.sh and stop_webserver.sh scripts from docs directory.

[ansys-reviewer-bot]

Thanks for opening a Pull Request. If you want to perform a review write a comment saying:

@ansys-reviewer-bot review

[sourcery-ai]

Reviewer's Guide

Refactors shell scripts across CI workflows, devcontainer setups, and documentation to enforce consistent shebangs, descriptive headers, error handling patterns, standardized variable usage, and adds shellcheck linting; also introduces a unified documentation webserver script and updates the changelog.

File-Level Changes

Change	Details	Files
Standardize script headers and shebangs	Added missing #!/bin/bash lines to scripts Inserted detailed comment blocks describing purpose, usage, and environment variables	.ci/collect_mapdl_logs_locals.sh .ci/start_mapdl.sh .ci/display_logs_locals.sh .ci/display_logs_remote.sh .ci/build_matrix.sh .ci/substitute_defective_gif.sh .devcontainer/devcontainer-local/start.sh .devcontainer/codespaces-dev/start.sh .devcontainer/codespaces-docs/start.sh
Refactor file operations and error handling	Prefixed file globs with ./ to avoid pattern ambiguity Added
Unify variable assignments and default logic	Removed unnecessary exports on internal variables Used parameter expansion for default values (e.g. AUTH_USER) Standardized uppercase naming and grouped export statements	.ci/start_mapdl.sh .ci/build_matrix.sh
Add shellcheck to pre-commit and update changelog	Added shellcheck-py hook in pre-commit config Configured shellcheck args for script linting Created changelog entry for the shellcheck hook	.pre-commit-config.yaml doc/changelog.d/4026.miscellaneous.md
Introduce unified documentation webserver script	Added doc/webserver.sh to start/stop a Python HTTP server Removed old start_webserver.sh and stop_webserver.sh Logged server output and PID for easier management	doc/webserver.sh doc/start_webserver.sh doc/stop_webserver.sh

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @germa89 - I've reviewed your changes and they look great!

Prompt for AI Agents

Please address the comments from this code review:
## Individual Comments

### Comment 1
<location> `.ci/display_logs_remote.sh:12` </location>
<code_context>
 # Displaying MAPDL files
-FILE_PAT=./"$LOG_NAMES"/*.err
-if compgen -G "$FILE_PAT" > /dev/null ;then for f in "$FILE_PAT"; do echo "::group:: Error file $f" && cat "$f" && echo "::endgroup::" ; done; fi || echo "Failed to display the 'out' files."
+FILE_PAT="./$LOG_NAMES/*.err"
+if compgen -G "$FILE_PAT" > /dev/null ;then for f in $FILE_PAT; do echo "::group:: Error file $f" && cat "$f" && echo "::endgroup::" ; done; fi || echo "Failed to display the 'out' files."

-FILE_PAT=./"$LOG_NAMES"/*.log
</code_context>

<issue_to_address>
Expanding glob patterns without quotes may break on filenames with spaces.

Using unquoted glob patterns can cause issues with filenames containing spaces or special characters. Use 'for f in "$FILE_PAT"' or a safer approach like 'find ... | while read f; do ...' to handle such cases correctly.
</issue_to_address>

### Comment 2
<location> `.ci/start_mapdl.sh:21` </location>
<code_context>
     echo "It is latest-ubuntu. Using 'ansys' script to launch"
-    export EXEC_PATH=ansys
-    # export P_SCHEMA=/ansys_inc/ansys/ac4/schema
+    EXEC_PATH=ansys
+    # P_SCHEMA=/ansys_inc/ansys/ac4/schema

 elif [[ $MAPDL_VERSION == *"ubuntu"* ]] ; then
</code_context>

<issue_to_address>
P_SCHEMA is not exported in the 'latest-ubuntu' branch, unlike other branches.

Downstream scripts may fail if they rely on P_SCHEMA being set, causing inconsistent behavior across branches.
</issue_to_address>

### Comment 3
<location> `doc/webserver.sh:49` </location>
<code_context>
+(cd _build/html &> /dev/null ) || { echo -e "${ERROR} HTML docs files are not found!${END_FT}"; exit 1; }
+which python &> /dev/null || { echo -e "${ERROR} Python is not available!${END_FT}" && exit 1; }
+
+python -m http.server "${PORT}" >> "${LOG_FILE}" 2>&1 & echo -n "$!" > webserver.pid
+
+echo "The pid of the web server is $(cat webserver.pid)"
</code_context>

<issue_to_address>
Writing the PID to webserver.pid may not work as intended due to backgrounding.

Use parentheses to group the background process and PID write to ensure the correct PID is captured: (python ... & echo $! > webserver.pid).
</issue_to_address>

### Comment 4
<location> `doc/webserver.sh:36` </location>
<code_context>
+PORT="${2:-${PORT:-8000}}"
+
+if [[ "$STOP" == "stop" ]]; then
+    pkill -9 -f 'm http.server' && echo -e "${BLUE}${BOLD}All web servers have been stopped.${END_FT}" || echo -e "${ERROR} Web server could not be stopped or does not exist.${END_FT}"
+    exit 0
+fi
</code_context>

<issue_to_address>
Using 'pkill -f' with a short pattern may kill unintended processes.

Consider using a more specific pattern or tracking the server's PID to avoid terminating unrelated processes.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Copilot]

Pull Request Overview

Refactors documentation webserver scripts into a single script, standardizes shell scripting across devcontainers and CI, and adds ShellCheck to pre-commit.

• Introduce unified webserver.sh for starting/stopping docs server; remove legacy start/stop scripts
• Add ShellCheck hook and fix shebangs or disable warnings in devcontainer startup scripts
• Standardize error handling, glob patterns, and cd safety in CI helper scripts

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
doc/webserver.sh	New unified start/stop server script
doc/stop_webserver.sh	Removed legacy stop script
doc/start_webserver.sh	Removed legacy start script
.pre-commit-config.yaml	Added ShellCheck pre-commit hook
.devcontainer/*/start.sh	Fixed shebangs and added ShellCheck disables
.ci/*.sh	Standardized cd error handling, glob patterns, and variable usage

Comments suppressed due to low confidence (4)

doc/webserver.sh:59

• Reference to 'stop_webserver.sh' is outdated since this script replaces separate start/stop scripts. Update the instruction to use './webserver.sh stop'.

    echo -e "${INFO} Remember to stop the server when you are done using 'stop_webserver.sh'.${END_FT}"

.ci/display_logs_locals.sh:10

• Script header references MAPDL_LOGS_DIR and OUTPUT_DIR, but the script uses LOG_NAMES. Update the documentation to match actual variables used.

# 

.ci/collect_mapdl_logs_locals.sh:10

• Header doc variables (MAPDL_LOGS_DIR, OUTPUT_DIR) don't match the code using LOG_NAMES. Align header with script behavior or use the documented variables.

#   MAPDL_LOGS_DIR   - Directory containing MAPDL log files to collect.

.ci/build_matrix.sh:171

• [nitpick] Consider quoting $GITHUB_OUTPUT in the redirection to handle paths with spaces: >> "$GITHUB_OUTPUT".

echo "matrix=${JSON}" >> "$GITHUB_OUTPUT"

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.81%. Comparing base (cb35c0c) to head (68741d9).
Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4086      +/-   ##
==========================================
- Coverage   91.85%   91.81%   -0.05%     
==========================================
  Files         187      187              
  Lines       15033    15033              
==========================================
- Hits        13809    13802       -7     
- Misses       1224     1231       +7     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[germa89]

@pyansys-ci-bot LGTM.

[pyansys-ci-bot]

✅ Approving this PR because germa89 said so in here 😬