Allow packages to build documentation if they inherit classes in this package

doc/changelog.d/651.fixed.md

@@ -0,0 +1 @@
+Allow packages to build documentation if they inherit classes in this package

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

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 <https://github.com/pyansys/openapi-common/issues>`_ page
 to submit questions, report bugs, and request new features.
 
 To reach the support team, email `pyansys.support@ansys.com <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 <sphinx:usage/extensions/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 <sphinx:usage/extensions/intersphinx>`, then Sphinx
+   automatically adds a cross-reference to the relevant location in the API
+   documentation for this package.

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -6,3 +6,7 @@ Heimdal
 Kerberos
 OpenAPI
 THIRDPARTY
+(?i)docstrings?
+subclassed
+subclassing
+Intersphinx

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 <ansys.openapi.common.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: