From 8cca7b28bef880df93f4df8d78fbbcce8f023daa Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 13:25:06 -0400 Subject: [PATCH 01/11] Handle versionadded directives for subclassed classes --- doc/source/conf.py | 24 ++++++++++++++++++ doc/source/contributing.rst | 37 +++++++++++++++++++++++++++- src/ansys/openapi/common/_session.py | 31 ++++++++++++++--------- 3 files changed, 79 insertions(+), 13 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index d68f76e0..2b380193 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,10 @@ import sys from ansys_sphinx_theme import get_version_match +from sphinx.errors import NoUri +from sphinx.util import logging + +logger = logging.getLogger(__name__) from ansys.openapi import common @@ -18,6 +22,10 @@ # The short X.Y version release = version = common.__version__ +# Add the openapi-common-standalone tag to indicate the docs should be built +# in standalone mode +tags.add("openapi-common-standalone") + # -- General configuration --------------------------------------------------- extensions = [ "sphinx.ext.autodoc", @@ -137,3 +145,19 @@ # Output file base name for HTML help builder. htmlhelp_basename = "openapicommondoc" + + +# -- Suppress warnings raised by missing xrefs to intersphinx link to this documentation when generating docs -- +def suppress_missing_intersphinx_xrefs(app, env, node, contnode): + ref_target = node.attributes["reftarget"] + if ref_target.startswith("openapi-common"): + ref_doc = node.attributes["refdoc"] + logger.info( + f"Suppressing warning for missing intersphinx xref from {ref_doc} to {ref_target}" + ) + raise NoUri + + +def setup(app): + logger.info("Registering 'suppress_missing_intersphinx_xrefs' callback") + app.connect("missing-reference", suppress_missing_intersphinx_xrefs) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9b089138..0c624a14 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -10,7 +10,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 +25,43 @@ 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:`~ansys.openapi.common.ApiClientFactory` is typically subclassed, and the builder +methods are shown within the sub-classing package's documentation as part of **that** +module's subclass. + +One common example of where this is important is in ``.. versionadded::`` directives. +To document that a certain feature was added in version 2.1 of ``ansys.openapi.common``, +always use the following approach: + +.. code-block:: restructuredtext + + .. only:: openapi-common-standalone + + .. versionadded:: 2.1 + + .. only:: not openapi-common-standalone + + .. tip:: + Added to :doc:`ansys-openapi-common ` in version 2.1. + + +The ``openapi-common-standalone`` tag is added automatically during the documentation +build process, which ensures that: + +* When building the documentation for this package, the ``.. versionadded::`` + directive is used. +* When building the documentation for a package that inherits from this package, + the more generic ``.. tip::`` directive is used, and additional context about + the change is provided. diff --git a/src/ansys/openapi/common/_session.py b/src/ansys/openapi/common/_session.py index 1d6217e7..d6ef25e9 100644 --- a/src/ansys/openapi/common/_session.py +++ b/src/ansys/openapi/common/_session.py @@ -86,7 +86,14 @@ class AuthenticationScheme(Enum): Used to specify an authentication scheme used when connecting to the server with credentials. - .. versionadded:: 2.1 + .. only:: openapi-common-standalone + + .. versionadded:: 2.1 + + .. only:: not openapi-common-standalone + + .. tip:: + Added to :doc:`ansys-openapi-common ` in version 2.1. """ AUTO = "auto" @@ -210,11 +217,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,13 +233,17 @@ 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:: openapi-common-standalone + + .. versionadded:: 2.1 + + .. only:: not openapi-common-standalone - .. versionadded:: 2.1 + .. tip:: + Added to :doc:`ansys-openapi-common ` in version 2.1. Returns ------- From 97be99472b17852f15329eb59b5ec24c7ab1915b Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 13:36:46 -0400 Subject: [PATCH 02/11] Include intersphinx explaination --- doc/source/conf.py | 1 + doc/source/contributing.rst | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index 2b380193..5c13767f 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -50,6 +50,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 0c624a14..ccf944cd 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -65,3 +65,10 @@ build process, which ensures that: * When building the documentation for a package that inherits from this package, the more generic ``.. tip::`` directive is used, and additional context about the change is provided. + +.. note:: + + The example code includes a link to the documentation for this package via + :doc:`Intersphinx `. The Intersphinx + mapping for this package should always be set to ``openapi-common`` to + ensure the links included in this package are generated correctly. From b7b889ef81e86c8172a8b52d0e1e7b7b629b1e69 Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 13:58:55 -0400 Subject: [PATCH 03/11] Fix tag, clean up inheritable type references --- doc/source/conf.py | 5 ++-- doc/source/contributing.rst | 39 +++++++++++++++++++++++----- src/ansys/openapi/common/_session.py | 32 +++++++++++------------ 3 files changed, 51 insertions(+), 25 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 5c13767f..ba03e17d 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,9 +22,8 @@ # The short X.Y version release = version = common.__version__ -# Add the openapi-common-standalone tag to indicate the docs should be built -# in standalone mode -tags.add("openapi-common-standalone") +# Add a tag to indicate the docs should be built in standalone mode +tags.add("OpenapiCommonStandaloneBuild") # -- General configuration --------------------------------------------------- extensions = [ diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index ccf944cd..4bb33a59 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -39,10 +39,37 @@ When contributing to this package, always consider that many docstrings are view the context of a package that inherits from classes defined in this package. For example, :class:`~ansys.openapi.common.ApiClientFactory` is typically subclassed, and the builder methods are shown within the sub-classing package's documentation as part of **that** -module's subclass. +module's subclass. The advice in this section ensures that a sub-classing package can +build documentation that inherits docstrings from this package. -One common example of where this is important is in ``.. versionadded::`` directives. -To document that a certain feature was added in version 2.1 of ``ansys.openapi.common``, +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 this package. +To make these references explicit when they occur outside of this package, always use the following approach: .. code-block:: restructuredtext @@ -61,10 +88,10 @@ The ``openapi-common-standalone`` tag is added automatically during the document build process, which ensures that: * When building the documentation for this package, the ``.. versionadded::`` - directive is used. + directive is used and *implicitly* refers to version 2.1 of this package. * When building the documentation for a package that inherits from this package, - the more generic ``.. tip::`` directive is used, and additional context about - the change is provided. + the more generic ``.. tip::`` directive is used, and *explicitly* refers to + version 2.1 of this package with a hyperlink to provide additional context. .. note:: diff --git a/src/ansys/openapi/common/_session.py b/src/ansys/openapi/common/_session.py index d6ef25e9..583c8b36 100644 --- a/src/ansys/openapi/common/_session.py +++ b/src/ansys/openapi/common/_session.py @@ -86,11 +86,11 @@ class AuthenticationScheme(Enum): Used to specify an authentication scheme used when connecting to the server with credentials. - .. only:: openapi-common-standalone + .. only:: OpenapiCommonStandaloneBuild .. versionadded:: 2.1 - .. only:: not openapi-common-standalone + .. only:: not OpenapiCommonStandaloneBuild .. tip:: Added to :doc:`ansys-openapi-common ` in version 2.1. @@ -117,7 +117,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. """ @@ -182,7 +182,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 @@ -204,7 +204,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() @@ -236,18 +236,18 @@ def with_credentials( authentication_scheme : ~ansys.openapi.common.AuthenticationScheme The authentication scheme to use. - .. only:: openapi-common-standalone + .. only:: OpenapiCommonStandaloneBuild .. versionadded:: 2.1 - .. only:: not openapi-common-standalone + .. only:: not OpenapiCommonStandaloneBuild .. tip:: Added to :doc:`ansys-openapi-common ` in version 2.1. Returns ------- - :class:`~ansys.openapi.common.ApiClientFactory` + ~ansys.openapi.common.ApiClientFactory Original client factory object. Raises @@ -311,7 +311,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 @@ -356,12 +356,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 @@ -475,9 +475,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. """ @@ -501,7 +501,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 @@ -530,7 +530,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: @@ -551,7 +551,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: From 5cab658234c596fb479ebc2fc97fec8bea86ae11 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 22 Aug 2024 18:00:24 +0000 Subject: [PATCH 04/11] chore: adding changelog file 651.fixed.md --- doc/changelog.d/651.fixed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/651.fixed.md diff --git a/doc/changelog.d/651.fixed.md b/doc/changelog.d/651.fixed.md new file mode 100644 index 00000000..9d9d80da --- /dev/null +++ b/doc/changelog.d/651.fixed.md @@ -0,0 +1 @@ +Ensure directives included in docstrings support subclassing by other packages \ No newline at end of file From a1c9d622e39c3b430f4dcc4cea456c17b00b0ca8 Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 14:05:10 -0400 Subject: [PATCH 05/11] vale fixes --- doc/source/contributing.rst | 20 ++++++++++--------- .../config/vocabularies/ANSYS/accept.txt | 3 +++ 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 4bb33a59..0f11439d 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,5 +1,7 @@ .. _contributing_openapi: +.. currentmodule:: ansys.openapi.common + ========== Contribute ========== @@ -37,10 +39,10 @@ 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:`~ansys.openapi.common.ApiClientFactory` is typically subclassed, and the builder -methods are shown within the sub-classing package's documentation as part of **that** -module's subclass. The advice in this section ensures that a sub-classing package can -build documentation that inherits docstrings from this package. +:class:`~.ApiClientFactory` is typically subclassed, and the builder methods are shown +within the sub-classing package's documentation as part of **that** module's subclass. +The advice in this section ensures that a sub-classing package can build documentation +that inherits docstrings from this package. Docstring type references ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -66,11 +68,11 @@ 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 this package. -To make these references explicit when they occur outside of this package, -always use the following approach: +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 this package. To make these references explicit when they occur outside of this +package, always use the following approach: .. code-block:: restructuredtext diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 70ada02b..1392898e 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -6,3 +6,6 @@ Heimdal Kerberos OpenAPI THIRDPARTY +(?i)docstrings? +subclassed +Intersphinx From ec526012964d0053687b50ce991891f3cec0713b Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 15:05:30 -0400 Subject: [PATCH 06/11] Use API cross-reference directly --- doc/source/conf.py | 20 ---------------- doc/source/contributing.rst | 34 ++++++++++++++-------------- src/ansys/openapi/common/_session.py | 7 ++++-- 3 files changed, 22 insertions(+), 39 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index ba03e17d..3d2ad8d6 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,10 +3,6 @@ import sys from ansys_sphinx_theme import get_version_match -from sphinx.errors import NoUri -from sphinx.util import logging - -logger = logging.getLogger(__name__) from ansys.openapi import common @@ -145,19 +141,3 @@ # Output file base name for HTML help builder. htmlhelp_basename = "openapicommondoc" - - -# -- Suppress warnings raised by missing xrefs to intersphinx link to this documentation when generating docs -- -def suppress_missing_intersphinx_xrefs(app, env, node, contnode): - ref_target = node.attributes["reftarget"] - if ref_target.startswith("openapi-common"): - ref_doc = node.attributes["refdoc"] - logger.info( - f"Suppressing warning for missing intersphinx xref from {ref_doc} to {ref_target}" - ) - raise NoUri - - -def setup(app): - logger.info("Registering 'suppress_missing_intersphinx_xrefs' callback") - app.connect("missing-reference", suppress_missing_intersphinx_xrefs) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 0f11439d..e622960d 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -68,36 +68,36 @@ 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 +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 this package. To make these references explicit when they occur outside of this -package, always use the following approach: +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:: openapi-common-standalone + .. only:: OpenapiCommonStandaloneBuild .. versionadded:: 2.1 - .. only:: not openapi-common-standalone + .. only:: OpenapiCommonStandaloneBuild .. tip:: - Added to :doc:`ansys-openapi-common ` in version 2.1. + Added to :class:`~ansys.openapi.common.ClassName` in version 2.1 of + ``ansys-openapi-common``. - -The ``openapi-common-standalone`` tag is added automatically during the documentation -build process, which ensures that: +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 this package, - the more generic ``.. tip::`` directive is used, and *explicitly* refers to - version 2.1 of this package with a hyperlink to provide additional context. +* 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:: - The example code includes a link to the documentation for this package via - :doc:`Intersphinx `. The Intersphinx - mapping for this package should always be set to ``openapi-common`` to - ensure the links included in this package are generated correctly. + If the inheriting package has configured + :doc:`Intersphinx `, then Sphinx will + automatically add a cross-reference to the relevant location in the API + documentation for this package. diff --git a/src/ansys/openapi/common/_session.py b/src/ansys/openapi/common/_session.py index 583c8b36..0f00a449 100644 --- a/src/ansys/openapi/common/_session.py +++ b/src/ansys/openapi/common/_session.py @@ -93,7 +93,8 @@ class AuthenticationScheme(Enum): .. only:: not OpenapiCommonStandaloneBuild .. tip:: - Added to :doc:`ansys-openapi-common ` in version 2.1. + Added as :class:`~ansys.openapi.common.AuthenticationScheme` in version 2.1 of + ``ansys-openapi-common``. """ AUTO = "auto" @@ -243,7 +244,9 @@ def with_credentials( .. only:: not OpenapiCommonStandaloneBuild .. tip:: - Added to :doc:`ansys-openapi-common ` in version 2.1. + Added to + :meth:`ApiClientFactory.with_credentials ` + in version 2.1 of ``ansys-openapi-common``. Returns ------- From e45ad930ea0d11d533b59c375d5bab6340b54444 Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 15:09:21 -0400 Subject: [PATCH 07/11] Vale fixes --- doc/source/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index e622960d..9a13aa0f 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -98,6 +98,6 @@ entity that contains the change. This approach ensures that: .. note:: If the inheriting package has configured - :doc:`Intersphinx `, then Sphinx will - automatically add a cross-reference to the relevant location in the API + :doc:`Intersphinx `, then Sphinx + automatically adds a cross-reference to the relevant location in the API documentation for this package. From 671d7bc6b1a2b17fed682b38c3964022c357f4a6 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 22 Aug 2024 19:14:49 +0000 Subject: [PATCH 08/11] chore: adding changelog file 651.fixed.md --- doc/changelog.d/651.fixed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog.d/651.fixed.md b/doc/changelog.d/651.fixed.md index 9d9d80da..3cb8fc34 100644 --- a/doc/changelog.d/651.fixed.md +++ b/doc/changelog.d/651.fixed.md @@ -1 +1 @@ -Ensure directives included in docstrings support subclassing by other packages \ No newline at end of file +Allow packages to build documentation if they inherit classes in this package \ No newline at end of file From c9db719a9167b5b2bcf982078779fcb86d389c2d Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 15:23:06 -0400 Subject: [PATCH 09/11] Be consistent with hyphens --- doc/source/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9a13aa0f..fe283ce8 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -40,8 +40,8 @@ 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 sub-classing package's documentation as part of **that** module's subclass. -The advice in this section ensures that a sub-classing package can build documentation +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 From 40c136f47de22771f95ad9ad55163630b8e4cade Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 15:24:46 -0400 Subject: [PATCH 10/11] Fix vale --- doc/styles/config/vocabularies/ANSYS/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 1392898e..eca9bb0d 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -8,4 +8,5 @@ OpenAPI THIRDPARTY (?i)docstrings? subclassed +subclassing Intersphinx From 1a88fde24f03707375776d40c1ef78ecff9bd4be Mon Sep 17 00:00:00 2001 From: Andy Grigg Date: Thu, 22 Aug 2024 16:48:29 -0400 Subject: [PATCH 11/11] Update doc/source/contributing.rst Co-authored-by: Doug Addy --- doc/source/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index fe283ce8..dc89dc30 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -80,7 +80,7 @@ outside of this package, always use the following approach: .. versionadded:: 2.1 - .. only:: OpenapiCommonStandaloneBuild + .. only:: not OpenapiCommonStandaloneBuild .. tip:: Added to :class:`~ansys.openapi.common.ClassName` in version 2.1 of