diff --git a/.readthedocs.yml b/.readthedocs.yml index 5b8a44a..2a84f3c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,9 +1,4 @@ --- -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required version: 2 build: @@ -11,19 +6,10 @@ build: tools: python: "3.12" -# Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py -# Build documentation with MkDocs -#mkdocs: -# configuration: mkdocs.yml - -# Optionally build your docs in additional formats such as PDF and ePub -formats: all - -# Optionally set the version of Python and requirements required to build your docs python: install: - - requirements: requirements.txt - requirements: docs/requirements.txt + - path: . diff --git a/README.md b/README.md index 3aa6654..72baab3 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ To learn about how to use the OpenAEV Python client and read some examples and c ### API reference -To learn about the methods available for executing queries and retrieving their answers, refer to [the client API Reference](https://openaev-client-for-python.readthedocs.io/en/latest/pyoaev/pyoaev.html). +To learn about the methods available for executing queries and retrieving their answers, refer to [the client API Reference](https://openaev-client-for-python.readthedocs.io/en/latest/autoapi/index.html). ## Tests diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py index 80a4a18..748f559 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,65 +1,54 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# import os import sys sys.path.insert(0, os.path.abspath("..")) - -# -- Project information ----------------------------------------------------- - project = "OpenAEV client for Python" copyright = "2024, Filigran" author = "OpenAEV Project" - -# The full version, including alpha/beta/rc tags release = "1.10.1" master_doc = "index" - -autoapi_modules = {"pyoaev": {"prune": True}} - pygments_style = "sphinx" -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ "sphinx.ext.autodoc", "sphinx.ext.inheritance_diagram", - "autoapi.sphinx", + "autoapi.extension", "sphinx_autodoc_typehints", ] -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +autoapi_dirs = ["../pyoaev"] +autoapi_options = [ + "members", + "undoc-members", + "private-members", + "show-inheritance", +] -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +autodoc_inherit_docstrings = False +# Inherited docstrings from stdlib base classes are noisy — suppress them +_INHERITED_DOCSTRING_MARKERS = [ + "Create a collection of name/value pairs.", # enum.Enum + "str(object='') -> str", # str +] -# -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" +def _suppress_inherited_docstring(app, what, name, obj, options, lines): + """Remove inherited stdlib docstrings from generated API docs.""" + if what == "class" and lines: + joined = "\n".join(lines) + if any(marker in joined for marker in _INHERITED_DOCSTRING_MARKERS): + lines.clear() + + +def setup(app): + app.connect("autodoc-process-docstring", _suppress_inherited_docstring) -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst index 5b66af8..a9d07c5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,7 @@ OpenAEV client for Python ========================= - The pyoaev library is designed to help OpenAEV users and developers to interact with the OpenAEV platform API. - The Python library requires Python >= 3. .. toctree:: @@ -11,12 +9,9 @@ The Python library requires Python >= 3. :caption: Contents: client_usage/getting_started.rst - pyoaev/pyoaev - Indices and tables ================== - * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt index 7b94d45..622bdef 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ -autoapi==2.0.1 -sphinx==8.2.3 +sphinx==9.1.0 +sphinx-autoapi==3.4.0 +astroid==3.3.8 sphinx-autodoc-typehints==3.2.0 -sphinx_rtd_theme==3.0.2 +sphinx_rtd_theme==3.1.0