diff --git a/doc/changelog.d/651.fixed.md b/doc/changelog.d/651.fixed.md new file mode 100644 index 00000000..3cb8fc34 --- /dev/null +++ b/doc/changelog.d/651.fixed.md @@ -0,0 +1 @@ +Allow packages to build documentation if they inherit classes in this package \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index d68f76e0..3d2ad8d6 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,6 +18,9 @@ # The short X.Y version release = version = common.__version__ +# Add a tag to indicate the docs should be built in standalone mode +tags.add("OpenapiCommonStandaloneBuild") + # -- General configuration --------------------------------------------------- extensions = [ "sphinx.ext.autodoc", @@ -42,6 +45,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3.11", None), "requests": ("https://requests.readthedocs.io/en/latest", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), } # numpydoc configuration diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9b089138..dc89dc30 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,5 +1,7 @@ .. _contributing_openapi: +.. currentmodule:: ansys.openapi.common + ========== Contribute ========== @@ -10,7 +12,6 @@ with this guide before attempting to contribute to OpenAPI-Common. The following contribution information is specific to OpenAPI-Common. - Clone the repository -------------------- @@ -26,7 +27,77 @@ run: 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, +:class:`~.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 :doc:`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: + +.. code-block:: restructuredtext + + .. 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 + :doc:`Intersphinx `, then Sphinx + automatically adds a cross-reference to the relevant location in the API + documentation for this package. diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 70ada02b..eca9bb0d 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -6,3 +6,7 @@ Heimdal Kerberos OpenAPI THIRDPARTY +(?i)docstrings? +subclassed +subclassing +Intersphinx diff --git a/src/ansys/openapi/common/_session.py b/src/ansys/openapi/common/_session.py index 1d6217e7..0f00a449 100644 --- a/src/ansys/openapi/common/_session.py +++ b/src/ansys/openapi/common/_session.py @@ -86,7 +86,15 @@ class AuthenticationScheme(Enum): Used to specify an authentication scheme used when connecting to the server with credentials. - .. versionadded:: 2.1 + .. only:: OpenapiCommonStandaloneBuild + + .. versionadded:: 2.1 + + .. only:: not OpenapiCommonStandaloneBuild + + .. tip:: + Added as :class:`~ansys.openapi.common.AuthenticationScheme` in version 2.1 of + ``ansys-openapi-common``. """ AUTO = "auto" @@ -110,7 +118,7 @@ class ApiClientFactory: ---------- api_url : str Base URL of the API server. - session_configuration : SessionConfiguration, optional + session_configuration : ~ansys.openapi.common.SessionConfiguration, optional Additional configuration settings for the requests session. """ @@ -175,7 +183,7 @@ def connect(self) -> ApiClient: Returns ------- - :class:`ApiClient` + ~ansys.openapi.common.ApiClient Client object that can be used to connect to the server and perform API operations. Raises @@ -197,7 +205,7 @@ def with_anonymous(self: Api_Client_Factory) -> Api_Client_Factory: Returns ------- - :class:`~ansys.openapi.common.ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. """ self.__test_connection() @@ -210,11 +218,7 @@ def with_credentials( username: str, password: str, domain: Optional[str] = None, - authentication_scheme: Union[ - Literal[AuthenticationScheme.AUTO], - Literal[AuthenticationScheme.BASIC], - Literal[AuthenticationScheme.NTLM], - ] = AuthenticationScheme.AUTO, + authentication_scheme: AuthenticationScheme = AuthenticationScheme.AUTO, ) -> Api_Client_Factory: """Set up client authentication for use with provided credentials. @@ -230,17 +234,23 @@ def with_credentials( Password for the connection. domain : str, optional Domain to use for connection if required. The default is ``None``. - authentication_scheme : AuthenticationScheme - The authentication scheme to use instead of using the ``WWW-Authenticate`` header. The default is - :attr:`~.AuthenticationScheme.AUTO` which uses the ``WWW-Authenticate`` header to determine the optimal - authentication scheme. Valid schemes for this method are :attr:`~.AuthenticationScheme.BASIC` or - :attr:`~.AuthenticationScheme.NTLM`. + authentication_scheme : ~ansys.openapi.common.AuthenticationScheme + The authentication scheme to use. + + .. only:: OpenapiCommonStandaloneBuild + + .. versionadded:: 2.1 + + .. only:: not OpenapiCommonStandaloneBuild - .. versionadded:: 2.1 + .. tip:: + Added to + :meth:`ApiClientFactory.with_credentials ` + in version 2.1 of ``ansys-openapi-common``. Returns ------- - :class:`~ansys.openapi.common.ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. Raises @@ -304,7 +314,7 @@ def with_autologon(self: Api_Client_Factory) -> Api_Client_Factory: Returns ------- - :class:`~ansys.openapi.common.ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Current client factory object. Raises @@ -349,12 +359,12 @@ def with_oidc( Parameters ---------- - idp_session_configuration : :class:`~ansys.openapi.common.SessionConfiguration`, optional + idp_session_configuration : ~ansys.openapi.common.SessionConfiguration, optional Additional configuration settings for the requests session when connected to the OpenID identity provider. Returns ------- - :class:`~ansys.openapi.common.OIDCSessionBuilder` + ~ansys.openapi.common.OIDCSessionBuilder Builder object to authenticate via OIDC. Notes @@ -468,9 +478,9 @@ class OIDCSessionBuilder: Parameters ---------- - client_factory : ApiClientFactory + client_factory : ~ansys.openapi.common.ApiClientFactory Parent API client factory object that will be returned once configuration is complete. - session_factory : OIDCSessionFactory, optional + session_factory : ~ansys.openapi.common.OIDCSessionFactory, optional OIDC session factory object that will be configured and used to return an OAuth-supporting session. """ @@ -494,7 +504,7 @@ def with_stored_token(self, token_name: str = "ansys-openapi-common-oidc") -> Ap Returns ------- - :class:`ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. Raises @@ -523,7 +533,7 @@ def with_token(self, refresh_token: str) -> ApiClientFactory: Returns ------- - :class:`ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. """ if self._session_factory is None: @@ -544,7 +554,7 @@ def authorize(self, login_timeout: int = 60) -> ApiClientFactory: Returns ------- - :class:`ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. """ if self._session_factory is None: