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 OpenAPI-Common.

The following contribution information is specific to OpenAPI-Common.

Clone the repository

To clone and install the latest version of OpenAPI-Common in development mode, run:

git clone https://github.com/pyansys/openapi-common
cd openapi-common
pip install .

Post issues

Use the OpenAPI-Common Issues page to submit questions, report bugs, and request new features.

To reach the support team, email pyansys.support@ansys.com.

Documentation conventions

When contributing to this package, always consider that many docstrings are viewed within the context of a package that inherits from classes defined in this package. For example, ApiClientFactory is typically subclassed, and the builder methods are shown within the subclassing package’s documentation as part of that module’s subclass. The advice in this section ensures that a subclassing package can build documentation that inherits docstrings from this package.

Docstring type references

In cases where a class is intended to be subclassed, internal type references should be fully qualified. For example, instead of:

Parameters
----------
authentication_scheme : AuthenticationScheme
    The authentication scheme to use.

use:

Parameters
----------
authentication_scheme : ~ansys.openapi.common.AuthenticationScheme
    The authentication scheme to use.

This ensures that other packages that inherit from this package are able to resolve these types via Intersphinx.

References to this package

Docstrings often contain implicit and explicit references to the package they are documenting. One common example of an implicit reference is in .. versionadded:: directives, where the directive implicitly refers to a version of the package being documented. To make these references explicit when they occur outside of this package, always use the following approach:

.. only:: OpenapiCommonStandaloneBuild

    .. versionadded:: 2.1

.. only:: not OpenapiCommonStandaloneBuild

    .. tip::
       Added to :class:`~ansys.openapi.common.ClassName` in version 2.1 of
       ``ansys-openapi-common``.

Where :class:`ansys.openapi.common.ClassName` is a reference to the relevant entity that contains the change. This approach ensures that:

• When building the documentation for this package, the .. versionadded:: directive is used and implicitly refers to version 2.1 of this package.

• When building the documentation for a package that inherits from classes defined in this package, the more generic .. tip:: directive is used, and explicitly refers to version 2.1 of this package.

Note

If the inheriting package has configured Intersphinx, then Sphinx automatically adds a cross-reference to the relevant location in the API documentation for this package.