diff --git a/README.rst b/README.rst index f31a2503b..8cd8a93bd 100644 --- a/README.rst +++ b/README.rst @@ -64,13 +64,24 @@ All sources are located in ``_ folder. speos = Speos(host="localhost", port=50098) -Documentation -------------- +Documentation and issues +------------------------ Documentation for the latest stable release of PySpeos is hosted at `PySpeos Documentation `_. -Documentation is stored in ``_ folder and generated using `Sphinx`_. +In the upper right corner of the documentation's title bar, there is an option for switching from +viewing the documentation for the latest stable release to viewing the documentation for the +development version or previously released versions. + +On the `PySpeos Issues `_ page, +you can create issues to report bugs and request new features. On the `PySpeos Discussions +`_ page or the `Discussions `_ +page on the Ansys Developer portal, you can post questions, share ideas, and get community feedback. + +To reach the project support team, email `pyansys.core@ansys.com `_. + +The documentation sources are stored in ``_ folder and generated using `Sphinx`_. To build it manually : .. code:: bash diff --git a/doc/changelog.d/470.maintenance.md b/doc/changelog.d/470.maintenance.md new file mode 100644 index 000000000..a799f6d30 --- /dev/null +++ b/doc/changelog.d/470.maintenance.md @@ -0,0 +1 @@ +add project required info \ No newline at end of file diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 000000000..cf7ae17fd --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,153 @@ +Contribute +########## + +Overall guidance on contributing to a PyAnsys library appears in the +`Contributing `_ topic +in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar +with this guide before attempting to contribute to PySpeos. + +The following contribution information is specific to PySpeos. + +Clone the repository +-------------------- + +To clone and install the latest PySpeos release in development mode, run +these commands: + +.. code:: + + git clone https://github.com/ansys-internal/pyspeos + cd pyspeos + python -m pip install --upgrade pip + pip install -e . + + +Post issues +----------- + +Use the `PySpeos Issues `_ +page to submit questions, report bugs, and request new features. When possible, you +should use these issue templates: + +* Bug, problem, error: For filing a bug report +* Documentation error: For requesting modifications to the documentation +* Adding an example: For proposing a new example +* New feature: For requesting enhancements to the code + +If your issue does not fit into one of these template categories, you can click +the link for opening a blank issue. + +To reach the project support team, email `pyansys.core@ansys.com `_. + +View documentation +------------------ + +Documentation for the latest stable release of PySpeos is hosted at +`PySpeos Documentation `_. + +In the upper right corner of the documentation's title bar, there is an option +for switching from viewing the documentation for the latest stable release +to viewing the documentation for the development version or previously +released versions. + +Adhere to code style +-------------------- + +PySpeos follows the PEP8 standard as outlined in +`PEP 8 `_ in +the *PyAnsys Developer's Guide* and implements style checking using +`pre-commit `_. + +To ensure your code meets minimum code styling standards, run these commands:: + + pip install pre-commit + pre-commit run --all-files + +You can also install this as a pre-commit hook by running this command:: + + pre-commit install + +This way, it's not possible for you to push code that fails the style checks:: + + $ pre-commit install + $ git commit -am "added my cool feature" + ruff.....................................................................Passed + ruff-format..............................................................Passed + codespell................................................................Passed + check for merge conflicts................................................Passed + debug statements (python)................................................Passed + check yaml...............................................................Passed + trim trailing whitespace.................................................Passed + Validate GitHub Workflows................................................Passed + Add License Headers......................................................Passed + +Build the documentation +----------------------- + +.. note:: + + To build the full documentation, you must have a running SpeosRPC server + because it is used to generate the examples in the documentation. It is also + recommended that the service is running as a Docker container. + + If you do not have the SpeosRPC server installed, you can still build the + documentation, but the examples are not generated. To build the + documentation without the examples, define the following environment variable:: + + # On Linux or macOS + export BUILD_EXAMPLES=false + + # On Windows CMD + set BUILD_EXAMPLES=false + + # On Windows PowerShell + $env:BUILD_EXAMPLES="false" + +To build the documentation locally, you must run this command to install the +documentation dependencies:: + + pip install -e .[doc] + +Then, navigate to the ``docs`` directory and run this command:: + + # On Linux or macOS + make html + + # On Windows + ./make.bat html + +The documentation is built in the ``docs/_build/html`` directory. + +You can clean the documentation build by running this command:: + + # On Linux or macOS + make clean + + # On Windows + ./make.bat clean + +Run tests +--------- + +PySpeos uses `pytest `_ for testing. + +Prerequisites +^^^^^^^^^^^^^ + +Prior to running the tests, you must run this command to install the test dependencies:: + + pip install -e .[tests] + + +Running the tests +^^^^^^^^^^^^^^^^^ + +To run the tests, you need to first start navigate to the root directory of the repository and run this command:: + + pytest + +.. note:: + + The tests require the SpeosRPC server to be installed and running on your machine. + The tests fail if the service is not running. It is recommended for the SpeosRPC server + to be running as a Docker container. diff --git a/doc/source/index.rst b/doc/source/index.rst index 2c77902b9..1d5de877e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -37,6 +37,12 @@ PySpeos documentation |version| Learn how to use PySpeos with examples that demonstrate its capabilities. + .. grid-item-card:: Contribute :fa:`people-group` + :link: contributing + :link-type: doc + + Learn how to contribute to the PySpeos codebase + or documentation. .. toctree:: :hidden: @@ -46,3 +52,5 @@ PySpeos documentation |version| getting_started/index api/index examples + contributing + changelog diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 02a8e0ddd..4f74e890d 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -8,7 +8,7 @@ This section provides an overview of the PySpeos library, explaining its key concepts. PySpeos overview -====================== +================ PySpeos is a Python client to communicate with the Ansys SpeosRPC server. diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 0c0ec97c6..60007c235 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -5,6 +5,8 @@ exitance Lumerical (?i)pyansys (?i)pyspeos +pytest +Solver (?i)Speos Zemax SpeosRPC \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 5b7e8afb0..8d94a740c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,21 +9,22 @@ description = "A Python wrapper for Ansys Speos" readme = "README.rst" requires-python = ">=3.10" license = {file = "LICENSE"} -authors = [ - {name = "ANSYS, Inc.", email = "pyansys.support@ansys.com"}, -] -maintainers = [ - {name = "PyAnsys developers", email = "pyansys.maintainers@ansys.com"}, -] +authors = [{name = "ANSYS, Inc.", email = "pyansys.core@ansys.com"}] +maintainers = [{name = "ANSYS, Inc.", email = "pyansys.core@ansys.com"}] classifiers=[ "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "Intended Audience :: Science/Research", + "Intended Audience :: Manufacturing", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - "Private :: Do Not Upload", + "Topic :: Software Development :: Libraries", + "Topic :: Scientific/Engineering :: Physics", + "Topic :: Scientific/Engineering :: Information Analysis", ] dependencies=[ "protobuf>=3.20,<6",