Feat: Comprehensive documentation for Modbus Simulator (README.rst and JSON guide)

[FedericoMusa]

Versions
Python: 3.11+.png]

OS: Windows 11 Enterprise LTSC

Pymodbus: 3.8.0.dev (latest dev branch)

Description
The current pymodbus/server/simulator/README.rst is blank, and as noted in the TODO.rst file, there is a significant need to "Document simulator general" and "Document JSON".

Since the simulator is a complex tool involving a Modbus server, a Datastore, and a REST API, I propose to create a comprehensive README from scratch that will serve as the primary guide for this sub-package.

The new documentation will cover:

Architecture & Workflow: How the simulator initializes using the internal or custom setup.json.

Detailed JSON Schema: A complete reference for the setup.json structure, including server_list, device_list, and register definitions.

Web Console & API: Instructions for using the REST interface and the browser-based console (defaulting to port 8081).

Operational Integration: Practical examples using the pymodbus.simulator entry point to ensure a persistent and verifiable simulation environment.

This work aims to close the gaps identified by Jan Iversen regarding "silent starts" and user confusion when no registers are explicitly defined.

[janiversen]

We do not store documentation in the source path, have a look at the docs directory, there are already quite a lot of documentation.

Also just to be clear it is not a sub-package, it is an integral part of pymodbus.

Apart from that it would be nice to have more documentation....not sure though that architecture should be done as part of simulator documentation, it is much more general.

[janiversen]

Could it be you have not noticed

https://pymodbus.readthedocs.io/en/latest/

which is our online documentation.

[FedericoMusa]

Hi Jan,

First, my apologies again for the initial confusion regarding the documentation path; I’ve now fully pivoted to the /doc directory as you instructed.

To follow up on the approval of my PR regarding the simulator startup warnings:

I have verified on Windows 11 LTSC that my new warning logs are triggering correctly. During this test, I noticed a significant discrepancy: while server.rst and web.rst currently state that these features are 'not available', my local logs confirm the Modbus server is listening on 5020 and the HTTP server is active on 8081.

I propose to fix this by:

Populating simulator.rst: Transforming the 'WORK IN PROGRESS' index into a proper README for the simulator.

Updating sub-pages: Replacing the 'not available' placeholders with actual instructions that match the current dev behavior and my recent code changes.

Documenting JSON: Completing the configuration guide in datamodel.rst.

Since my code is already helping users in the terminal, I’d like to ensure the official documentation provides the same level of support. May I proceed with the PR?

[janiversen]

We do not want to have README distributed in the code.

Did you not that there are 2 simulator documentation path, you should work with the 3x path, the other is really work in progress.

[janiversen]

and of course you may proceded! but avoid the readme.

[janiversen]

The reason we do not want múltiple README is that it indicates sub-packages, something which is really sending the wrong signal.

We are very observant to have a clear API that does not ask users to address lower level directorios. This gives us freedom to change internal structures as we see fit.

[FedericoMusa]

I've completed the updates following your guidance on the 3.x path and the API cleanliness.

1. Code 'Armouring': I modified pymodbus/server/simulator/main.py. The simulator now explicitly validates the existence of the configuration file after parsing arguments. If the file is missing, it logs a FATAL error and performs a sys.exit(1). This prevents the 'silent start' in an empty state we discussed.

2. Official Documentation: Following the 3.x path, I've updated doc/source/library/simulator/config.rst. I added a new section 'Starting the Simulator' that details all command-line parameters (flags), ensuring the technical reference is centralized in the official Sphinx docs.

3. Cleanup: I've avoided adding any new README files in the source directories to keep the package structure clean.

Ready for your final review!"

[janiversen]

No need to keep this open, since you have started to make PR´s